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1 Introduction 

This document specifies a Programming Interface (PI) and corresponding Information Model (IM) 
which constitute Release 1 .0 CAD Framework Initiative Standard for Design Representation data. This 
document is the work of the CFI Design Information Technical Committee's 1 .0 Design Representation 
Working Group. 

1.1 Statement of Purpose 

The goal of the CFI Design Information Technical Committee's 1 .0 Design Representation Working 
Group is to define a means for CAD tools to create, access, or modify electronic design data in other 
CAD tools or databases. This is in support of the CFI goals of tool interoperability, tool 
interchangeability, data substitution, and data translation. 

The Design Representation Working Group's approach to this problem is to define a formal information 
model (IM) and a programming interface (called the DR-PI) based on the IM. The Information Model 
identifies the relevant object types in the domain of interest and specifies the attributes of each object 
type, including its relationships to other objects. qj 

m 

Release 1 .0 of the IM and the DR-PI is limited to the domain of ELECTRICAL CONNECTIVITY C/) 
information. The scope for the IM and the DR-PI is defined by the connectivity information needed for ~ ' 
netlisters (EDIF, VHDL, . . .), logic simulators, timing analyzers, synthesis tools, layout tools, and > 
flatteners, all of which work on hierarchical electrical connectivity data. ^ 

1.2 Problem Statement a5 

m 

Tools integrated into a CAD framework (or otherwise providing interoperability) require access to _ 

design data. A standard means of interactive (run-time) access can avoid translation from one design Q 

data format to another. There are two parts to this problem: (1) defining a specific common access Q 

mechanism for design data and (2) achieving sufficient consensus across the industry that this specific 3 
solution is acceptable and useful. Unless the second part is satisfied, it is unlikely that the CFI DR-PI 
will become a standard. 



So, the 1 .0 DR Working Group must do two things: 

Define a particular means for CAD tools to represent, access, and manipulate design data, and 
Achieve a consensus on that particular means among the members of the committee in order to drive 
the formation of a common guideline for the industry. Both are substantial problems, and they must be 
solved in parallel. 



1.3 Solution Approach 
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An approach has been defined for solving each of the two problems. 



1.3.1 The Design Data Access Problem 

In the initial meetings of the DR Working Group, the committee quickly decided on an interface- 
onented approach for solving the design data access problem. The approach is to define a Programming 
Interface (PI) which may be implemented in various programming languages (initially in C) and invoked 
directly from CAD tools. This programming interface is called the Design Representation Programming 
Interface, or "DR-PI." It was also quickly decided that, to define the DR-PI, an Information Model (IM) 
for the data to be handled by the DR-PI must first be defined. The IM shows abstractly what design 
^formation is made accessible via the DR-PI. The IM represents both the organization and the 
semantics of that information. 



Note that the IM and the DR-PI do not constitute the design of any particular database facility. The IM is 
not a data model. Instead, each implementor (or provider) of the DR-PI must perform the appropriate 
mapping between the data model of their actual database and the organization of the CFI Design 
Representation Information Model. Particular data models and the transformations behind them can (and 
likely will) be proprietary to particular vendors. 

The DR-PI provides access to actual design information, and it also provides an interface to a particular 
system's data without revealing the underlying implementation. It is a mask which is "put on" by that 
system and through which all access and manipulation of the data is provided. There is no implication 
whatsoever that the underlying data must be physically organized exactly like the IM. 

To provide this access to the design information, the DR-PI is "handle-" or Object ID- (OID) based No 
data structures are created or returned directly. Instead, the DR-PI defines a set of primitive types: such 
as integer, float, and string, and enumerated types: such as for specification of port direction, and OIDs 
that provide the "handles" to instances of the entities defined by the Information Model. 

OIDs may not be assumed to be pointers and may never be de-referenced directly by DR-PI users. 
Access to both the attributes and relationships of a design object is only via DR-PI procedures applied to 
its OID. In particular, the C structure member operators "." and "->" are never used to access fields of a 
design object because the OID need not be a pointer (though it may be one in a particular 
implementation). 

The Information Model is presented in the form of diagrams using the EXPRESS-G notation, as English 
text describing those diagrams, and as EXPRESS language text [1]. Each procedure in the DR-PI 
corresponds to some operation on design data in the domain specified by the IM. When possible, 
EXPRESS is used to define the semantics of those operations. When not, English text is used. Both 
EXPRESS and English are used to state the rules which are to be enforced as the information is 
manipulated. 



1.3.2 The Consensus-Building Problem 

Achieving the consensus of a large group of technical people with widely differing personal experience 
is a complex, laborious task. As the DR Working Group has grappled with this problem, an approach 
has grown out of the many attempts at listing the issues and bringing them to a state of closure. 
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This approach is based on democracy and electronic-mail. During meetings, different people will 
present technical approaches to the problems under consideration. Issues and concerns raised by 
working group members now must be submitted in writing. Between the meetings, these issues and 
others are distributed electronically. The issues are presented in a form that allows the members to vote 
their agreement or disagreement. When disagreement is voted, a member can supply a counter-proposal 
to be voted on by the group. This approach is proving to be an objective, unemotional procedure for 
obtaining decisions. 



1.4 Scope 

The scope of the Information Model is restricted to NETLIST or ELECTRICAL CONNECTIVITY 
information. This corresponds approximately to the EDIF Netlist View, encompassing Cells, Ports, 
Nets, Instances, and Port Instances. 
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2 Definitions 



The following definitions are used in this document: 
Attributes 

An entity is defined in terms of a set of attributes, which represent the entity's essential traits, qualities, 
or properties. Attributes can contain "primitive'' data type values such as strings, integers, reals, and 
enumerations, or an attribute of one entity can be one or more other entities. EXPRESS does not 
distinguish between an entity's attributes and its relationships as separate notions. Rather, each attribute 
is also a relationship to the type that represents its value; see [1] in Section 7. "References" . 

Entity (Type) 

An entity represents some thing or concept that is important in a schema An entity type provides 
expressions which define the entity. An entity instance is the realization of a specific case of the entity 
type. Thus while there is an entity type named "CELL," the cell named "Half-Adder" is an Entity 
Instance of the type CELL. The word entity used alone means entity type. An entity is defined in terms 
of its data and behavior. The data definition is given as a set of attributes. Behavior is defined in terms 
of constraints and operations [1]. 

Entity-Level Model 

An Entity-level model is an EXPRESS-G model that represents the definitions and their relations, which 
comprise a single schema [ 1 ]. 

EXPRESS 

An information modeling language defined by the EXPRESS Language Reference Manual [1]. This 
document also describes the graphical notation EXPRESS-G. 

EXPRESS-G 

The graphical notation for EXPRESS, which is described in Annex D of the EXPRESS Language 
Reference Manual [ 1 ]. 

Objects— Entity Instances 

Specific (allocated) cases of entity types, such as a particular "CELL," e.g., "Half-Adder" or "Adder" or 
"My 64 Bit ALU." 

Policy 

Rules restricting how entities and their operations may be manipulated. 
Programming Interface 
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A set of procedures or functions used by an application to (in the case of DR) access design data. 
Relationships 

Attributes of entities that model references to one or more other entities. EXPRESS does not distinguish 
between attributes and relationships explicitly. 

Schema 

A schema encompasses a set of entity and other declarations which have a related meaning and purpose. 
A schema can contain other schemas [1]. 

Schema-Level Model 

A schema-level model is an EXPRESS-G model which shows the relations between single schemas. It is 
an abstraction of a model removing much of the detail. Schema-level models should only show schemas, 
no entities or types. 

Session 

A session is defined as the interval of time in a program which starts with the "Initiate PI" procedure and 
ends with the "Quit PI" procedure [2]. 

Subtype and Supertype 

A subtype is a tiling which is different from other things of the same general kind. The entity which 
represents all varieties of that same general kind is called the supertype entity. For any supertype entity 
A which has a subtype entity B, the following statement is true: 

Every BismA, but not every A is a J?. 

Type 

A type is used to associate an attribute or variable with a data representation. In EXPRESS, the type is 
die kind of an entity or variable. Some types are basic, e.g., integer, real, or string. Other types are more 
specialized and are defined by the user. Every entity forms a type. 
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3 The Information Model 



One of the primary tasks of the Design Representation Working Group was to define a common 
Information Model (IM) for design representation. This IM serves as the basis for the Design 
Representation Programming Interface (DR-PI), which can he used by CAD tools to manipulate design 
information. 

NOTE: While every effort has been made to ensure the accuracy of the IM, if there are any 
discrepancies between the IM and the DR-PI, the definitions in the DR-PI will take precedence. 



3.1 Structure of the Information Model Description 

The remainder of this section provides a detailed description of an Information Model for representing 
electronic circuits. Ultimately, most aspects of circuit structure (i.e., schematics, layouts, and netlists) 
will be represented. However, at present, hierarchical netlist connectivity is the single aspect covered by 
this model. 

In an effort to manage the definition process, the IM has been partitioned. Each major portion of the 
model is described in a separate section using textual descriptions and information model diagrams. The 
most primitive or low-level concepts are described first, followed by descriptions of additional entities 
and types needed to build up to the final model. 

As mentioned previously, the information model described in this document will be constructed in the 
EXPRESS language [1 ]. One of the primary goals for using EXPRESS is to capture the information 
model explicitly in a computer readable format EXPRESS provides a syntax for defining data types, 
data entities, the behavior among entities, and inheritance among the definition of entities. This 
description will include "fragments" of the EXPRESS text corresponding to the concept being described. 
These fragments do not represent the entire model. For example, this section does not present the 
definition of the function unique_names() Refer to Appendix A for the entire EXPRESS text 
description of the DR connectivity model including any functions used, such as uniquejnamesO- Refer 
to [1] for a description of the EXPRESS language. All of the diagrams in this document are drawn using 
the EXPRESS-G graphical notation which is briefly explained in the next section. Refer to [1] also for a 
detailed description of EXPRESS-G. 

The first diagram is shown in Figure 3.1, "Base Object Model Diagram," and is described in Section 3.3. 
The base object model captures the top of the entity hierarchy used to describe the information model. 

The second diagram, shown in Figure 3.2, "Base Connectivity Model Diagram." This model represents a 
high-level abstraction of the basic connectivity model for electronic circuits. 



3.2 Description of EXPRESS-G 

EXPRESS is a language used to model information. The language is described in the ISO document, 
EXPRESS Language Reference Manual, TCI 84/SC4 WG5 Document N14 [1 ]. EXPRESS can be used to 
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model: 

• Information units that package data elements, 

• Constraints on data elements or the information units as a whole, and 

• Operations on those information units [1]. 

All of the information models presented in this document will be described formally in the EXPRESS 
language (refer to Appendix A, "Information Model"). 

EXPRESS is a language. Hence, information models written in EXPRESS are textual. However, a 
graphical notation has also been defined, dubbed EXPRESS-G. This notation is described in detail in 
Annex D of the document cited above. However, since EXPRESS-G is a new notation for many readers, 
a brief description is provided here. 

EXPRESS-G is a graphical notation for the display of information models. The notation only supports a 
subset of the EXPRESS language, and therefore EXPRESS-G models are normally abstractions of 
EXPRESS models [!]• There are equivalent notations for bit-mapped graphics and ASCII character or 
"typed" diagrams. EXPRESS-G has symbols to represent EXPRESS entities, user-defined types, base 
types, relationships (required and optional), and inheritance. Table 3.1, "Express-G Legend", provides a 
legend for understanding EXPRESS-G diagrams. 
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Table 3.1 EXPRESS-G Legend 

The small circle on the end of relationship arcs indicates direction only; it has nothing to do with 
cardinality. The cardinality of a relationship will be annotated on the relationship using text. Refer to the 
EXPRESS manual [1] for more informati on about EXPRESS-G. 



3.3 The Base Object Model 



The entire Design Representation Information Model is derived from a single entity which models the 
basic, low-level behavior of any entity in the model. This low-level behavior is intended to capture the 
essence of the notion of an object The basic behavior of all objects in the DR model is that they will be 
typed and may have an optional list of properties associated with them. Additionally, many objects will 
have a name. The EXPRESS-G diagram for this basic object model is shown below in Figure 3.1 as an 
entity-level model. Following the figure is a more-detailed description of the entities and types depicted 
in the diagram. 
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Figure 3.1 Base Object Model Diagram 
3.3.1 Type: ObjectType 

TYPE cfidrObjectTypeT = ENUMERATION OP ( 
CFIDR_CELL, 
CFIDR_INST, 
CFIDR_LIB, 
CFIDR_NETBUNDLE , 
CFIDR_NETBUS, 
CFIDRJKETSCALAR , 
CFIDR^PORTBUNDLE , 
CFIDR^PORTBUS, 
CFIDR_PORTINSTBUNDLE , 
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CFIDR_PORTINSTBUS , 
CFIDR^PORTINSTSCALAR, 
CFIDR_PORTSCALAR, 
CFIDR_PROP, 

CF IDR_ENCAPSULATEDVI EW , 
C F I DR__NETL I STVT EW 
); 

END_TYPE; 

DESCRIPTION 

ObjectType defines all possible object types. Values of type cfidrObjectTypeT will be used 
as the value of the ObjectType attribute for all DR objects. These types should not be 
confused with the base object types defined by EXPRESS which include r eal, integer, 
string, boolean, and logical. 

RATIONALE 

All entities shall be typed. A fixed set of object types is needed to provide a common basis for 
the information in a design description which can be shared. Note that only the non-abstract 
entity types are included in this list since they are the only ty pes from which entity instances 
can be created. 

33.2 Type: Objectld 

TYPE cf idrObj ectldT = INTEGER; END_TYPE; 

TYPE cfidrCellldT = cf idrObjectldT; ENDJTYPE; 

TYPE cfidrEncapsulatedViewIdT = cf idrObjectldT; ENDJTYPE; 

TYPE cfidrlnstldT = cf idrObjectldT; ENDJTYPE; 

TYPE cfidrLibldT » cf idrObjectldT; END_TYPE; 

TYPE cfidrNamedObj ectldT - cf idrObjectldT; ENDJTYPE; 

TYPE cfidrNetldT = cf idrObjectldT; ENDJTYPE; 

TYPE cfidrNetBundleldT = cf idrObjectldT; ENDJTYPE; 

TYPE cfidrNetBusIdT = cf idrObjectldT; ENDJTYPE; 

TYPE cfidrNetScalarldT = cf idrObjectldT; ENDJTYPE; 

TYPE cfidrNetlistViewIdT = cf idrObjectldT; ENDJTYPE; 

TYPE cfidrPortBundleldT = cf idrObjectldT; ENDJTYPE ; 

TYPE cfidrPortBusIdT = cf idrObjectldT; ENDJTYPE; 

TYPE cfidrPortldT = cf idrObjectldT; ENDJTYPE; 
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TYPE cfidrPortlnstldT = cf idrObjectldT; ENDJTYPE; 

TYPE cf idrPortlnstBundleldT = cf idrObjectldT; ENDJTYPE; 

TYPE cfidrPortlnstBusIdT = cf idrObjectldT; ENDJTYPE; 

TYPE cfidrPortlnstScalarldT = cf idrObjectldT; ENDJTYPE ; 

TYPE cfidrPortScalarldT = cf idrObjectldT; ENDJTYPE ; 

TYPE cfidrPropIdT = cf idrObjectldT; ENDJTYPE ; 

TYPE cfidrViewIdT = cf idrObjectldT; ENDJTYPE; 

DESCRIPTION 

Programming Interfaces (Pis) will refer to objects by object identifiers (OIDs) which cannot 
be assumed to be C pointers or any other specific language data type. They will differ in 
different implementations because OIDs in any given system can be differ ent kinds of 
objects, and vendors need to be able to make changes to the definition of OIDs without 
forcing program structures to change. The EXPRESS code declares the cfidrObjectldT as 
INTEGER because it must use some Express primitive type. This does n ot mean an 
implementation must use an INTEGER. 

NOTE: The Architecture Working Group has decreed that all machines of the same processor 
architecture have a common cfidr.h header file and that the Object IDs should be twice the size of void * 
(i.e., twice the size of an address). 

RATIONALE 

Since all objects are typed and all objects are accessed via OIDs, an ID entity is required. 
The intent is that IDs are die "handles" through which objects are manipulated. An 
application tool should not be required to possess knowledge of the implementat ion of IDs 
to use them. They are non-transparent handles. 

CONSTRAINT 

IDs are valid for the current session only. Hence, IDs cannot be stored in a persistent database. 

In order to minimize a tool's need to explicitly test the type of an object, each type of object has a specific type for its 
ID. Therefore a tool usually should only need to determine whether a particular ID is valid. 

333 Entity: Object 

ENTITY cfidrObject 

ABSTRACT SUPERTYPE OF (ONEOF 
(cf idrNamedObject, cf idrPortlnst) ) ; 

ObjectType: cf idrObjectTypeT; 

Ob j ec t Id : cf idrOb j ec t IdT ; 

Props: SET 10:?] OF cfidrProp; 

WHERE unique_names { Props ) ; 
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END_ENTITY; 

DESCRIPTION 

The entity Object will be a supertype for every other entity defined in this information 
model It models the basic behavior of all objects: all objects are typed; all objects have a 
unique identifier (an ID); and all objects may have properties associate d with them. 

RATIONALE 

The DR Working Group intends this information model to be designed in an object-oriented 
fashion. In particular, the model will use inheritance so that common aspects of otherwise 
distinguished objects will be specified in a common root object The entity Object is the root 
of the entire inheritance graph. Since EXPRESS supports the modeling of multiple 
inheritance, this need not be the only root entity type. The intent is that this entity provide 
the minimal attributes that any (cfidr) object needs to be considered a valid member of the 
object community. 

CONSTRAINT 

The Name attribute of properties must be unique within the scope of a single object That is, no two properties 
associated with one object may have identical names. 

33.4 Entity: NamedObject 

ENTITY cfidrNamedObject 
SUBTYPE OF (cfidrObject) 

ABSTRACT SUPERTYPE OF (ONEOF(cf idrProp, cfidrLib, 
cfidrCell, cfidrView, 
cfidrPort, cfidrNet, cf idrlnst) ) ; 
Name: cf idrStr ingT ; 
END_ENTITY ; 

DESCRIPTION 

As with Object, NamedObject defines an entity which will serve a supertype for many other 
objects in the model. Any object which has a text name string will be defined as a subtype of 
NamedObject 

RATIONALE 

Using inheritance, the ability for an object to be named is modeled by making that object a 
subtype of NamedObject It is expected that many objects in the model will be named. Hence 
inheritance is used to ensure that a consistent notion of naming is defined and used for each 
object requiring a Name attribute. 

33.5 Entity: Prop 

ENTITY cfidrProp 

SUBTYPE OF (cfidrNamedObject); 
ValueType: cf idrValueTypeT; 
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PropValue: cf idrPropValue; 
Owner: cf idrObjec^- 

END.ENTITY; 

DESCRIPTION 

A Prop allows an application to effectively extend the database schema by including its own 
Object attributes as properties. A Prop consists of a name/value pair and can be associated 
with any object Prop values are typed (see ValueType below). 

RATIONALE 

No information model can explicitly model every need of every possible application tool 
Hence, the model must be inherently extensible to support additional information needs. 
The intent of the property entity is to partially provide this extensibility. Properties may be 
used to annotate other entities with additional information that is not formally part of the 
information model. 

CONSTRAINT 

When a Prop is removed, any Props associated with it are also removed. 
33.6 Type: ValueType 

TYPE cf idrValueTypeT = ENUMERATION OF 

( CFIDR_UNDEFINED_VALUETYPE , CFIDR_INT32, CFIDR_STRING, 

CFIDR_FLOAT32, CFIDR_BOOLEAN) ; 
ENEL.TYPE; 

TYPE cf idrPropValue = SELECT 

(cfidrBooleanT, cfidrInt32T, cf idrFloat32T, cf idrStringT) ; 
ENDJTYPE; 

DESCRIPTION 

These type definitions describe the valid types for values of the Value attribute of a Prop 
entity. The SELECT type PropValue allows the PropValue attribute of Prop to be any the 
four shown types. 

RATIONALE 

A Prop's value must be typed to provide a common model for properties. This may limit the 
extensibility of the model To allow user-definable property types is beyond the scope of the 
Information Model at this stage. 



3.4 Overview of the Base Connectivity Model (BCM) 

This section describes the portion of the model that represents hierarchical netlist connectivity. The Base 
Connectivity Model (BCM) is shown in Figure 3.2. 
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Figure 3.2 Base Connectivity Model Diagram 

This model represents the objects and relationships used to represent hierarchical netlists with bundles in 
CFI 1 .0.0 Design Representation. 

In Figure 3.2 there is no modeling significance to the gray entities, they are just to highlight the "main" 
entities in the model 

TTie following two sections describe the model shown in Figure 3.2. First, a conceptual description is 
given for the technique of representing connectivity using the model. Following that is a detailed 
description of each entity and type in the BCM diagr am and the constraints on their behavior. 



3.5 Base Connectivity Model Tutorial Description 

Although the probability is high that anyone reading this document has knowledge of hierarchical circuit 
connectivity and is familiar with at least one system for representing it, there is a reason for presenting 
an overview in tutorial fashion here. Specifically: the model asserts throughout rules about how entities 
in it are to be combined to represent a hierarchical netlist. This tutorial describes the entire model and all 
the rules in one place. Each of the rules will be stated again as constraints on the entities defined later in 
this section. 

Hierarchical design supports the notion of building up the behavior of a design by collecting and 
connecting together other designs. Each of the other designs can in turn be built from yet other designs, 
etc., recursively until a subdesign is reached which is composed of primitive design elements. In this 
case a primitive design element is one for which no further interior structure is known. Primitive design 
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elements are also referred to as leaf cells. 

A bottom-up example is to use a transistor as a primitive element or leaf cell. Transistors then are used 
to build and-gate, nand-gates, inverters, etc. These gates are used to build an exclusive-or-gate, which is 
used with other gates to build an half-ad der cell, which is used with other cells to build an adder cell, 
which is used with other cells to build an ALU, etc. 

In order to represent a hierarchical design, there must be a way to represent the design under 
consideration and the fact that it is composed of other designs which are connected in some way. In the 
model described herein, a particular implementation of a design is represented by the Ned istView entity. 
The inclusion of smaller designs of which a NetlistView is composed are represented by the Inst entity. 
The tenn Inst is an abbreviation for the word Instance. 

Instantiation is the act of using one design in the structure of another design. In this model, the design 
which is being used is the Inst, and the design in which an Inst is used is the NetlistView. As an analogy, 
think of the NetlistView as a printed circuit board and an Inst as a chip which is soldered down onto the 
circuit board. A NedistView may have more than one Inst within it and multiple Insts of a single design 
may be placed into a NetlistView. An Inst represents the use of one design within an other design. Each 
Inst represents an instantiation of one NetlistView within another NetlistView. 

An instantiation is not exactly a copy nor is it exactly a symbolic reference. For example, in a 
NetlistView named "Half- Adder" an Inst of a NedistView named "XOR" represents the fact that the 
design of an xor gate is used as a component in die design of a half-adder. 

Haying provided a representation for the hierarchical structure of designs using the NedistView and Inst 
entities, it is necessary next to provide a representation for interconnecting the Insts within a 
NetlistView. 

The connectors of a design are represented by the Port entity. A Port has a name and a direction. The 
direction of the Port defines how signal information flows through the Port. A signal either flows into 
the design or out from the design through the Port Or, in some cases, a Port is bidirectional and can 
conduct signal information both into and out of a design. 

The pins of an Inst are represented by the Portlnst entity. Since an Inst represents the use of a specific 
NetlistView, the Portlnsts belonging to an Inst correspond exactly to the Ports on the NedistView 
referenced by the Inst. For example, if an Inst "xorl" represents the use of an XOR gate within a design 
then each of that Inst's Portlnst entities will correspond to a single Port entity in the NetlistView of the 
XOR gate that was used to create this Inst. The correspondence between an Inst and the Net listView it 
represents is referred to as the "Describer Relationship". An Inst is completely "described" by the 
NetlistView it represents. This same corresponcence exists between a Portlnst and the Port it represents. 
Both the Inst and Portlnst entitie s contain a Describer attribute. 

The fact that Portlnst's attributes for name and direction are DescriberName and DescriberDirection 
indicate the close tie required between each Portlnst and its Describer Port. See Section 6. "View 
Selection", on how this very tight relationship between Insts/Portlnsts and their Describers/Ports can be 
relaxed. View Selection provides a mechanism to specify rules for choosing an alternative 
(substitutable) NedistView (and its correspo nding Ports) for any given Inst. 

To complete the initial model, the Net entity is used to represent each set of connections between 
Portlnsts and Ports within a NetlistView. When a collection of Portlnst and Port entities are associated 
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with a Net, it reflects the intention that each Portlnst and Port in the collection will have exactly the 
same signal information at all times. A Net may connect only Portlnsts, only Ports, or a mixture of the 
two. 

One final concept is that of bundles. In many scenarios, it is convenient for a designer to group a set of 
signals together and refer to the set as single signal. An example of this is the RS-232 standard signal set 
for the interconnection of serial communication equipment The RS-232 standard defines the set of 
signals expected to be found in the 25 pin connectors common on most telephone modems used to 
interconnect computer systems. An RS-232 cable has multiple wires which are bundled together into a 
single cable which can be connected once. In electronic design, there are times when it is convenient to 
refer to the RS-232 signal collection as a single signal, and there are times when it is necessary to refer 
to each individual signal separately. The same is true with respect to the connectors for RS-232 signals. 
The RS-232 connector bundles together 25 individual connectors. 

In the BCM, this concept is represented by introducing the notions of Scalar, Bundle, and Bus. A Scalar 
is an individual thing which may not be unbundled into anything else. A Bundle is an ordered collection 
and a Bus is an ordered collection with index values for each position. The idea of Scalar, Bundle, and 
Bus is applied to Nets, Ports, and Portlnsts. 

A Net may be either a NetScalar, a NetBundle, or a NetBus. In a sense, there are now 3 "types" of Net 
entities. A NetScalar entity represents one individual signal which may not be further decomposed into 
subsignals. A NetBundle entity is a collection of Nets, each of which is optionally a NetScalar (with no 
further substructure), a NetBundle, or a NetBus. A NetBus entity is a NetBundle with two additional 
attributes of Start and Step which define the range of Index values associate d with the Positions in the 
bundle. 

Thus NetBundles have only the Names for each Net and an implicit Position in the bundle for each Net. 
NetBusses are NetBundles mat also have an Index value for each position. This Index is restricted to be 
monotonically changing from position to position by a fixed integer Step (positive or negative) but may 
Start at any integer value. 

NetBundles do not hide the Names of their member nets. All Nets in any one NetlistView are required to 
have unique names. Nets can appear in more than one position in a given bundle and in more than one 
NetBundle. A given name for a Net in a part icular NetlistView always refers to the exact same Net 

A similar structure exists for Ports and Portlnsts, resulting in the definition of PortScalars, 
PortBundles, PortBusses, PortlnstScalars, PortlnstBundles and PortlnstBusses. The 
PortlnstBundles (and PortlnstBusses ) get their structure entirely from the corresponding PortBundles 
(and PortBusses). 

However, a significant difference from NetBundles is that PortBundles hide the Names of their members 
from other PortBundle contents (and from the names of the Ports mat are directly in the NetlistView). 
Thus Port Names may be reused without refe rring to the same object The other difference is that a 
PortBundle (and thus also a PortlnstBundle) cannot repeat a member in two different positions, therefore 
any one name only appears one time in a given bundle. 

The rules covering the interconnection of Ports and Portlnsts using Nets are complicated. To help clarify 
the explanation, the phrase "in-a-bundle" will be appended to the terms NetScalar, PortScalar, and 
PortlnstS calar to distinguish items contained by a bundle from items NOT contained by a bundle. 
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As explained prior to introducing the notion of a bundle, a Net represents a connection between Ports 
and/or Portlnsts. So it follows that a NetBundle will represent a connection between collections of Ports 
and Portlnsts. The following rules summarize t he bundle connectivity model: 

Allowed Connections: 

A NetScalar connects to [0:?] (read as zero or more) Port[inst]Scalars; 
A Port[Inst] Scalar is connected to [0: 1 ] (read as zero or one) NetScalar(s). 

When a Net that is in one (or more) NetBundle(s) connects to a Portfinst] that is in a Port[Inst]Bundle, 
this unplies a connection between all NetBundles containing the Net to the Port[Inst]Bundle containing 

A NetBundle connects to [0:?] Port[Inst]Bundles. 
A Port[Inst]Bundle is connected by [0:?] NetBundles. 

Disallowed Connections: 

A NetScalar connects to NO Port[Inst]Bundles directly, Port[Inst]Bundles are NOT directly connected 
by a NetScalar. 

A NetBundle connects NO Port[Inst]Scalars directly; 

A Port[Inst]Scalar is NOT directly connected by a NetBundle. 

Shorted Ports 

The connection of multiple PortScalars to one NetScalar creates a short between the PortScalars. This 
also means that the NetScalars connected to the PortlnstScalars which are instantiations of the shorted 
PortScalars are electrically equivalent Thus, th eir names are aliases of each other. 

NetBundle-TortBundle Asymmetry 

Why are bundled Nets and Ports treated differently? Many people initially expect them to be symmetric, 
since a Port is conceptually just a special Portion of a Net. But there are two reasons for this lack of 
symmetry: 

(1) cell content descriptions are substantially simplified, and 

(2) the cascading delete requirements are different for Nets and Ports. 

These are each explained in more detail below: 
(1) Simplified Logical Connectivity Descriptions 

The simplification comes from the elimination of complex facilities to represent the ripping of 
NetBundles to connect their constituents to other NetBundles or scalars. Instead, the default basis for 
Net connectivity within a cell is by unique Net name within the cell. That is, any scalar or bundle named 
X in a cell is the same scalar or bundle (connected to be electrically the same), where X may be any 
name. In fact, since they are the same, we no longer even think in terms of connectivity. All ap 
pearances in a cell of a Net (Scalar, Bundle, or Bus) named X are simply the same scalar, bundle, or bus. 

This principle applies to each NetlistView of a cell. Each NetlistView has its own separate Net name 
scope. However, NetScalars whose IsGlobal attribute is true are global in name scope such that all 
appearances of the same name on any global NetSc alar represent the same NetScalar. That is, all global 
NetScalars with the same name carry the same electrical signal. 
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Thus, while Nets may be "connected" by name inside a view, Net to Port connections cannot be by 
name. Since Port names are available outside the view, they are likely to be different as external needs 
require. Net to Port connections therefore must be exp licitly expressed, and not left to default 
Therefore Net to Port or Net to Portlnstance connections must be explicitly expressed or connected by 
the matching order of bundle constituents. 

(2) Cascading Deletion Semantics 

Secondly, the deletion semantics for NetBundles and PortBundles are different The deletion of a 
NetBundle must not cascade to delete the scalars within the NetBundle. NetScalars are the essence of 
the design, and NetBundles are just an artifact for conve nience. Conversely, the deletion of a 
PortBundle is the removal of that Port and all its constituents from the external appearance of the view. 
Thus, deletion of a PortBundle cascades to also delete all the constituent Ports within that PortBundle. 



3.6 Base Connectivity Model Detailed Description 

In this section, each entity in the BCM is described in detail. The content of the information for each 
entity is described along with any constraints on the behavior of the entity. 

3.6.1 Entity: Ub 

ENTITY cfidrLib 

SUBTYPE OF (cfidrNamedObject); 



Cells: SET [0:?] OF cfidrCell; 



WHERE 

unique_names (Cells) ; 
END_ENTITY; 

DESCRIPTION 

Lib is an abbreviation for Library. The Lib entity is intended to collect together all of the 
design data that shares a common set of characteristics. A Lib will contain a set of Cell 
entities on the Cells attribute. Each Cell represents a specific component of a design. The 
realization of a specific view type for a specific Cell is modeled by theView entity (described 
later). A Lib has no Owner attribute. 

The Name attribute for a Lib (inherited from NamedObject) is a single string which labels the Lib. 

RATIONALE 

The intent of the Lib entity is to model the well-known concept of a cell library. At 
minimum, a library will have a collection of cells with views of different types. The EDBF 
notion of a library should map to this concept in time (when technology inform ation is 
added). Since a Lib is an object, it may contain properties. Using properties, additional 
information may be loaded onto a Lib to support specific needs. To clarify the meaning of 
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these entities, consider the following examples: 

• Lib: a standard cell one micron component library or a library containing the entire definition of a 
microprocessor. 

• Cell: a Nand gate, an ALU, or a printed circuit board within a system. 

• View: the layout for a Nand gate or the schematic symbol for an ALU. 

CONSTRAINT 

A Lib's Name attribute must be unique with respect to all other lib names known by the current PI session. 

When a Lib is removed from a session {purged or destroyed), all the Cell and Prop objects contained by the Lib 
become inaccessible in the session. 

All Libs accessible during a session must have unique names. 
3.6.2 Entity: CeU 
ENTITY cfidrCell 

SUBTYPE OF (cf idrNamedObject) ; 



Owner: cfidrLib; 

Views: SET [0:?] OF cfidrViewr 



WHERE 

unique_names (Views) ; 
END_ENTITY; 

DESCRIPTION 

A Cell represents an abstract portion of a design that may be implemented with several 
Views. A Cell is owned by a Lib via the Owner attribute. To model the realization of 
multiple, specific implementations, a Cell provides a set of View entities t h rough the Views 
attribute. 

RATIONALE 

The generic notion of a design cell is intended here. A Cell is a specific component of a 
design such as an "Adder" or "ALU." However, the CeU entity does not imply a specific 
implementation of the component Specific implementations of a CeU are realiz ed in the 
View entities (described later). 

CONSTRAINT 

A Cell's Name attribute must be unique with respect to the names of all Cells in the set of Cells in the Owner Lib. 

Purging or destroying a Cell within a session causes any View and Prop entities owned by the CeU to become 
inaccessible. 

3.63 Entity: View 

ENTITY cfidrView 
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SUBTYPE OF (cfidrNamedObject) 

ABSTRACT SUPERTYPE OF (ONEOF 

(cf idrEncapsulatedView, cf idrNetlistView) ) ; 



Owner: cfidrCell; 
ViewType: cf idrStringT; 



END_ENTITY; 

DESCRIPTION 

A View entity represents an abstraction of the design* It represents a specific 
implementation of one particular Cell. As such, a View is owned by exactly one Cell via the 
Owner attribute. 

View is an abstract type. Specific views are either an EncapsulatedView, representing a type 
that is unknown to the DR-PI, or a NetlistView containing electrical connectivity 
information that is accessible through the DR-PI. Both types of View may also h ave their 
type further classified by the ViewType attribute string. 

RATIONALE 

In future versions of the model, the View entity will be further refined into additional sub- 
entities to partition the behavior and information associated with different aspects of Views 
(e.g., topology versus topography). 

CONSTRAINT 

A View's Name attribute must be unique with respect to all View names within die scope of a CelL 
3.6.4 Entity: EncapsulatedView 

ENTITY cf idrEncapsulatedView 



SUBTYPE OF (cf idrView) ; 



Key: cf idrStringT; 



END_ENTITY; 

DESCRIPTION 

An EncapsulatedView represents a view of the cell about which very little is known to the 
DR-PI. It is a place to "hook" outside information such as a file containing behavioral 
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information. 

The Key attribute is expected to typically be a file name or other such thing that allows a 
system to locate the actual information associated with this view. 

EncapsulatedViews may also have their type further classified by the ViewType attribute 
string* 

RATIONALE 

EncapsulatedView provides a standard way to associate outside information with a Cell 
without resorting to the intrinsically non-standard use of properties. 

NOTE: No mechanism is provided to access ports or other aspects within an EncapsulatedView. An 
EncapsulatedView must either already have internally-named Ports with the same names as used in the 
other Views, or some tool-specific mechanism must be u sed to relate between them. 

3.6.5 Entity: NetiistView 

ENTITY cfidrNetlistView 



SUBTYPE OF (cf idrView) ; 



Ports: LIST[0r?] OF cfidrPort; 
Nets: SET 10: ?] OF cfidrNet; 

Insts: SET [0:?] OF cfidrlnst; 



WHERE 

unique_names (Insts) ; 
unique_names(Nets) ; 
unique_naines ( Ports ) ; 



END_ENTITY; 

DESCRIPTION 

A NetiistView entity represents an abstraction of the design that uses instances of other 
NetlistViews and may itself be in turn instantiated in another NetiistView to build a design 
hierarchy. Each NetiistView represents the electrical connectivity of a specific 
implementation of the Owner Cell 

The NetiistView entity models the structure and electrical connectivity of a hierarchical netlist. It is 
similar in scope to the EDIF 2 0 0 NETLIST [5] view. Electrical connectivity refers here to the logical 
or electrical connections that carry logical o r electrical signals within and between die cells in the 
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design. 

Ports represent the "places" on the NetlistView where connections can be made to instances of this 
view. They provide access to the signals inside this view. 

Insts represent the hierarchical references to (or inclusion of) other NetlistViews in the definition of this 
NetlistView. 



Nets represent the signal caiTying connections between the Ports of this NetlistView and Portlnsts. 
Portlnsts are located on Insts and correspond to the Ports of the NetlistViews that describe each Inst. 
Port, Net, Inst, and Portlnst are each described further in the sections on those entities. 

RATIONALE 

A Cell may have more than one View including more than one NetlistView. Each View 
corresponds to some specific aspect of or alternative for implementing a Cell. 

The NetlistView models the essence of an electrical circuit netlist It is very similar to the 
basic information in the EDIF 2 0 0 NETLIST [5] view. 

The NetlistView entity represents a key concept in this model It embodies the concept of a 
piece of design that is defined by its interface Ports and optionally by instantiation and 
connection of other NetlistViews. This design piece itself can, in turn, be used (multiple 
times) in the definition of other Cell's NetlistViews. 

In future versions of the model, the NetlistView entity may be further refined into sub-types to 
distinguish between "contents" views with substructure (nets and insts) and "interface" views 
without substructure (ports [and maybe nets] only). Another dist inction can be made (as in the 
new EDIF 3 0 0) between logical connectivity and the structure used in implementing it with 
specific objects such as the graphics in a schematic or a symbolic layout view. For instance, 
additional structure is imposed on th e connectivity in a schematic by junctions, rippers, and off- 
page connectors. 

CONSTRAINT 

Each Port's Name attribute must be unique with respect to the names of all other Ports In the list of Ports. 
Each lust's Name attribute must be unique with respect to the names of all other Insts in the set of Insts. 
Each Net's Name attribute must be unique with respect to the names of all other Nets on the set of Nets. 
3.6.6 Entity: Inst 
ENTITY qfidrlnst 

SUBTYPE OF (cfidrNamedObject); 



Owner t cfidrNet listViow; 

Deocribor t cf idrNet lie tview; 
Portlnsts: LIST 10 tU OF of idrPortlnst; 
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DESCRIPTION 

The Inst entity models the hierarchical usage of a Netlis t View as a part of another 
NetlistView. The NetlistView which describes the Inst is in the Describer attribute. Insts also 
have Portlnsts corresponding one-to-one with the Ports of the instan tiated NetlistView. 
These are in die list that is the Portlnsts attribute. The containing NetlistView which is using 
this Inst is in the Owner attribute. 

RATIONALE 

Electronic design often creates new components by connecting existing components. The 
outcome is intrinsically hierarchical. To represent a hierarchy of connected components, the 
notion of instantiation is used. An existing component is placed within a ne w component by 
instantiation. The Inst entity realizes the instantiation of a component It is not exactly a 
copy nor is it exactly a reference. It is both at the same time. An Inst is intended to represent 
the usage of a component without duplicating the definition of the component each place it is 
used. Rather, the Inst provides an indirect reference to the definition of the instantiated 
component while also providing a location for information specific to the usage of the 
component at the point of inst antiation. 

CONSTRAINT 

A NetlistView may not instantiate itself either directly or indirectly. In other words, none of the instances in a view may 
be of that same view nor may they be of views which have instances of that same view or instances of views which 
have instances of that same view, etc. Simply put: no recursive instantiation is allowed. This however does not 
preclude instantiating another view of the same cell— something that might be done to collect views into pages, for 
instance. 

NOTE: The Programming Interface is only required to check for direct recursion because of the 
computational cost associated with checking for arbitrary indirect recursion. 

3.6.7 Entity: Port 

TYPE 

cfidrPort Owner « SELECT 

(cfidrBJetlietView, cfidrPort Bundle) ; 

END_TYPEj 
ENTITY cfidrPort 

SUBTYPE OF (cfidrNaunadObject) 

ABSTRACT SUPERTYPE OF OHEOF 

(cfidrPort Scalar , cfidrPortBundle) ; 



Owners c £ idr Port Owner ; 

DERIVED 

Positions cfidrmt32T f in<5Lpo8ition_in_awner( ) / 
ENDJBNTITYj 
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DESCRIPTION 

Ports are the means of communicating information between NetlistViews in a design 
hierarchy. Ports are the external interface for a NetlistView. They correspond to Portlnst 
entities when a NetlistView is instantiated. 

Port is an abstract type. All actual ports are either PortScalar, PortBundle, or PortBus. 

Internal to a NetlistView, a Port is connected to a Net, thus passing along information into 
this cell view and then to lower levels of die design hierarchy. 

A Port is owned either by a PortBundle or a NetlistView entity via the Owner attribute 
(which necessitates the introduction of the cfidrPortOwner SELECT TYPE). A NetlistView 
may have many Ports. 

The Position of a Port is the location of this particular port in the list of Ports in Owner. The 
initial or "leftmost" position is numbered 0 and each subsequent port has position equal to 
one more than that of the port to its "left ". Thus for a list with three ports (A, B, Q, A has 
position 0 and C has position 2. 

NOTE: Ports have position regardless of whether the Owner is a NetListView or a PortBundle; in 
both cases they are on a list of Ports. 

RATIONALE 

A Port represents visibility for any Net of a NetlistView such that, when that NetlistView is 
used as an Inst in another "higher" NetListView, the Net can be connected via the 
corresponding Portlnst to a Net hi the "higher" NetlistView. In a sense, placin g a Port on a 
Net Is declaring to the world that the Net is connectable from above in the hierarchy. It 
provides a "port of entry" to or an exit from the NetlistView. 

CONSTRAINT 

The Name attribute of a Port must be unique with respect to the Name attribute of every other Port on the list of Ports 
in the Owner fNeUistView or PortBundle). 

3.6.8 Entity: PortScalar 

ENTITY cfidr Port Scalar 

SUBTYPE OF (cfidr Port); 



Direction i cfidrPortDirection; 
NetScalar: OPTIONAL cfidrNot Scalar; 
END_ENTITY; 

DESCRIPTION 

A PortScalar is a subtype of the abstract Port entity. A PortScalar is a single connection 
point to signal information which may not be further divided into sub-parts. The direction 
of the PortScalar is specified with the Direction attribute. A For t's direction is specified by 
the PortDirectlon enumeration. A PortScalar is directly connected to a NetScalar via its 
NetScalar attribute. 
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RATIONALE 

A PortScalar is a "leaf 1 signal carrier. It provides a connection point to a single wire or 
signal carrier. 

Only PortScalar has a direction. PortBundles and PortBusses have no overall direction. 

3.6.9 Type: PortDlrection 

TYPE cfidr PortDlrection e ENUMERATION OF 
( CFIDR^UMDEFINED_PORTDIRECTION, 

C7XDXL.ZNFUT, 

CFIDR^_OUTPUT , 

CFIDRJO) f 
END_TYPE; 

DESCRIPTION 

This type defines the legal values for the Direction attribute of a PortScalar entity as well as 
for the derived attribute DescriberDirection for the PortlnstScalar entity. 

RATIONALE 

Port direction must be consistently specified to achieve an interoperable Design 
Representation model 

3.6.10 Entity; PortBundle 
ENTITY cfidr Port Bundle 

SUBTYPE OF (cfidrPort) 
SOTERTYPE OP (cf idrPortBus) ; 

Ports: LIST [0s?l OF UNIQUE cfidrPort; 

NetBundles i SET [0t?] OF cfidrNet Bundle; 
DERIVED 

Si ze t SIZE_OF ( Ports ) ; 
END_£NTITY; 

DESCRIPTION 

A PortBundle entity models the ability to group many Ports together and treat the group as 
a single entity under appropriate conditions. PortBundles have substructure. That is, a 
PortBundle contains other Port entities which are held in the Ports a ttribute. A PortBundle 
may be made up of PortScalars or other PortBundles hierarchically. 

A PortBundle is connected to 0 or more NetBundles via its NetBundles attribute. 
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RATIONALE 

The tutorial explanation for the BCM (Fi gure 3,2 P^Xjmnectivfty Mo de l magrjanjotn 
page_13_) contains a statement of the rationale for PortBundles. In general, PortBundles 
allow a group of PortScalars and other PortBu ndles to be treated as a single entity when it 
is appropriate and convenient to do so. 

CONSTRAINT 

PortBundles may not recursively contain themselves either directly or indirectly. The PI is required to check for 
direct recursion at PortBundle creation time but not to check for indirect recursion at that time due to the potential 
computational cost. 

3.6.11 Entity: PortBus 

ENTITY ofldrPortBus 

SUBTYPE OF (of idr PortBundle) i 

Start i cfidrmt32Tf 
Stop* c£idrXnt32Yy 
BND_EHTXTY; 

DESCRIPTION 

A PortBus entity is simply a PortBundle with additional attributes that associate a specific 
index value with each position in the bundle. 

Start is the index value for Position 3. 

Step is the difference in index values of Position n and n+1. 

RATIONALE 

Many different terminologies were discussed in the DR TSC for non-scalar or composite 
signals: bundles, arrays, groups, and busses were the most common terms. In most cases, 
regardless of name, die Bundle entity, an ordered grouping of items (unique in the case of 
Ports), has the correct semantics while all other terminology distinctions are based mostly 
on naming conventions. 

The only semantic distinction on which agreement could be reached was that, in addition to 
the characteristic of being an ordered group, sometimes these groups also had an index to 
identify each position, that the index usually changed monotonically in v alue, and that the 
index of position 0 might be any value. The term Bus is used for these groups in which the 
positions are indexed. 

CONSTRAINT 

In spite of the fact that, for some systems, the distinguishing characteristic of a Bus from a Bundle is that it is Indexed 
instead of having names for each position, the member Ports of a PortBus are also required to have names that are 
unique with respe ct to each other. This is because all PortBusses are PortBundles which have this constraint 

3.6.12 Entity: Portlnst 

TYPE 

cfidrPortlnfltOwner ■ ffELECT(cf idrlnat , of idr Fort Inst Bundle) j 
E8D__TYPB| 

SWT ITT cfidr Port Inst . 
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ABSTRACT SUPSRTTPB OF (OBBOF ( 

(ofidrPortXnetScal&r, cf idr Port Ixxat Bundle) ) 
SUBTYPE 07 (ofidrObjeot) j 



Owner i of idrPortlnotOwnerj 

Dofioriberi of idrPort; 



DERXVB 

DescriberSanei of idrStringT t- Describer. Baffle j 

EHD_ENTXTTj 

DESCRIPTION 

The Portlnst entity corresponds to a Port of a NetlistView which has been instantiated 
within another NetlistView. The Port which describes a Portlnst is available through the 
Describer attribute* The Name and Direction attribute of t he describer Port are propagated 
to the Name and Direction attributes of the Portlnst A Portlnst is owned by either an Inst or 
a PortlnstBundle via the Owner attribute (through the cfidrPortlnstOwner SELECT 
TYPE). 

RATIONALE 

A Net connected to a Portlnst implicitly passes along its information to the describer Port 
and thus down one level in the design hierarchy. A Portlnst is more like a pure reference 
than an Inst is with respect to the describer NetlistView. 

Portlnsts can have properties (via a set of Props) that are separate from any properties on 
the Describer Port There is no automatic mechanism in the DR-PI whereby Props on a Port 
also appear on a Portlnst The Props of the describer Port may be obtained by getting the 
Describer Port then getting the Props set from it 

CONSTRAINT 

An Inst has precisely one Portlnst for each Port on the Describer NetlistView of the Inst Each Portlnst is of 
comparable sub-type to the corresponding Port: i.e., PortlnstScalar for PortScalar, PortlnstBundle for PortBundle, 
and PortlnstBus for Po rtBus. Any Portlnst substructure of bundles (or busses) must match the substructure of the 
Describer Ports. 

3.6.13 Entity: PortlnstScalar 

EHTITY of idrPertXnstScel&r 
SUBTYPE 07 (ofidrPortXnat)i 

S2LP\o£idrPortXnst . Describer t of idr Port So alar; 
NetScalart OPTXOSftL c* idrSetScalarj 



DesoriberDlreotiont of Idr Port Direction i- 

Desorlber • Direct ioaj 

BHDJBBTITTj 



DESCRIPTION 
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As with PortScalar, the PortlnstScalar entity models the lowest level PorOnst A 
Portlns tScalar will have no further sub-parts. A PortlnstScalar is directly connected to a 
NetScalar via its NetScalar attribute. 

RATIONALE 

The PortlnstScalar is a reflection of die PortScalar only associated with Inst entities. The 
rationale is the same as for PortScalars. 

CONSTRAINT 

The Describer of the PortlnstScalar must be a PortScalar. 
3.6.14 Entity: PortlnstBundle 

ENTITY c f idr Port Ins t Bundle 
tiUBTIVK 0» (cfldr Port Inst) i 



SKLP\cfidrPortInst.DeBoriberi of idrPortBondlei 
Portlns ta i LIST [Of?} OF ONI QUE of idr Port Inst i 
Het Bundles t BET [Ot?) OP cridrHetBundlei 
EHD_J£HTI TY > 

DESCRIPTION 

A PortlnstBundle entity models the ability to group many Portlnsts together and treat the 
group as a single entity under appropriate conditions. PortlnstBundles have substructure. 
That is, a PortlnstBundle contains other Portlnst entities which are held i n the Portlnsts 
attribute. A PortlnstBundle may be made up of PortlnstScalars or other PortlnstBundles 
hierarchically. A PortlnstBundle is connected to 0 or more NetBundles via its NetBundles 
attribute. 

RATIONALE 

PortlnstBundles are a reflection of PortBundles only associated with the Inst entity. The 
rationale is the same as for PortBundles. 

CONSTRAINT 

The Describer of the PortlnstBundle must be a PortBun die. 
3.6.15 Entity: PortlnstBns 

ENTITY c f idr Port Inflt Bus 

SUBTYPE OF (cfidr PortlnstBundle) ; 
SBBXV8 

Start t cfidrlnt32T to Describer. Start ; j 
Stepi cfidrin*t33T to Describer . Stop i 
BHDJWTXTYl 

DESCRIPTION 

A PortlnstBus entity is simply a PortlnstBundle with additional attributes that associate a 
specific index value with each position in the bundle. 
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Start is the index value for Position 3. 

Step is the difference in index values of Position n and n+1. 

RATIONALE 

Many different terminologies were discussed in the DR TSC for non-scalar or composite 
signals: bundles, arrays, groups, and busses were the most common terms. In most cases, 
regardless of name, the Bundle entity, an ordered grouping of items (unique in the case of 
Portlnsts), has the correct semantics while all other terminology distinctions are based 
largely on naming conventions. 

The only semantic distinction on which agreement could be reached was that, in addition to 
the characteristic of being an ordered group, sometimes these groups also have an index to 
identify each position, that the index usually changes monotonically in v alue, and that the 
index of position 0 might be any value. The term Bus is used for these groups in which the 
positions are indexed. 

CONSTRAINT 

In spite of the fact that, for some systems, the distinguishing characteristic of a Bus from a Bundle is that it is indexed 
instead of having names for each position, the member Portlnsts of a PortlnstBus are also required to have names 
which are unique w ith respect to each other. This is because all PortlnstBusses are PortlnstBundles which have this 
constraint 

The Describer of the PortlnstBus must be a PortBus. 
3.6.16 Entity: Net 
ehtity cfidrKet 

SUBTYPE OF (cf idrNaxaedObJect) ; 
ABSTRACT flOPBRTTPB OF (OHBOF ( 

(cfidrKetBundle, c fidrHet Scalar >) , 



Owner i C C IdrNatlistVievf 

Porte t SET [Os?] OF ofldrFort; 

Portlnetei SET tOs?) OF of IdrPortXnatj 
HetBundlofli SET CO i?] OF oCldrttotBundlej 



SZZEOF< Porta) ♦ 8XZEOF< Portlnsts) >° 2; 
EHD_EHTITY| 



DESCRIPTION 

The Net passes information throughout the design hierarchy by connecting Ports and 
Portlnsts together. A Net is owned by a NetlistView via the Owner attribute. A Net may be 
hierarchically contained by zero or more NetBundles available through the < I>NetBundles 
attribute. 

RATIONALE 

The Net entity models the basic idea of connectivity. A net represents a set of connected 
things, namely, Ports and Portlnsts. When two Ports and/or Portlnsts are connected to a 
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Net, the implication is that those Ports and Portlnsts will all "see" die sam e signal 
information in the context of the circuit being represented* 

CONSTRAINT 

Each net must connect at least two things—eventually. 

3.6.17 Entity: NetScalar 

ENTITY o£idrSetSoalar 
SUBTYPE OF (Cfidxftot)f 

SKLFXcf idrSet.PortBi SET 10i?J OF c£ldrPortSc«lar> 
SELF\c£ldrffot . Portlnsts t SET 10 it) OF of Idr Port Inat Scalar f 
XeOlobalt cfidrBooleanT; 

END_EOTITY> 

DESCRIPTION 

The NetScalar entity models the lowest level Net which has no further sub-parts* A 
NetScalar connects to PortScalars and/or PortlnstScalars. Multiple PortScalars connected 
to the same NetScalar short the PortScalars and will cause aliasing of NetScalars a t the next 
level up in the hierarchy whenever the Owner NetlistView is used as an Inst and the 
corresponding Portlnsts are connected to Nets at that level 

A NetScalar is a " global net" when IsGlobal is TRUE. All global NetScalars with the same 
name are the same electrical net. 

RATIONALE 

To support the notion of Bundled signals, a concept is needed which represents a scalar 
signal value, but which has no further sub-signal components. 

3.6.18 Entity: NetBundle 

HWITY cfidrBetBundl© 

SUFBRTYPE OF (cf ldrHetBue) 
SUBTYPE OF (cfidrSet)j 

SKLF\c£idrBet . Ports i SET [0i?] OF cfidr Port Bundle* 
SEur\cf idrHet . Port In* te SET [0i?J OF cf idrPortlnstBundlej 
Metsi LIST (0i?) OF cfldrtfeti 

derive 

sisei sxza_OF(8et0>> 

EOT)_EHTITYi 

DESCRIPTION 

The NetBundle entity models aggregation of Net entities. The member Nets of a NetBundle 
are available via the Nets attribute. NetBundles may contain NetBundles to model multiple 
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levels of Net hierarchy. 
RATIONALE 

The NetBundle is needed to allow hierarchical and other aggregate signal structures to be 
represented in a consistent manner. Bundles allow groups of signals to be treated as a single 
entity when it is appropriate and expedient to do so. 

3.6.19 Entity: NetBus 

HWITY cf IdrZfetBus 

SUBTYPE OF (cfidrHetBundle)i 

Start i o£idrXnt32Tj 
Stept o£idrXnt32Tf 



DESCRIPTION 

A NetBus entity is simply a NetBundle with additional attributes that associate a specific 
index value with each position in the bundle. 

Start is the index value for Position 0. 

Step is the difference in index values of Position n and n+1. 

RATIONALE 

Many different terminologies were discussed in the DR Working Group for non-scalar or 
composite signals: bundles, arrays, groups, and busses were the most common terms. In 
most cases, regardless of name, the Bundle entity, an ordered grouping of items ( non- 
unique in the case of Nets), has the correct semantics while all other terminology distinctions 
are based mostly on naming conventions. 

The only semantic distinction on which agreement could be reached was that, in addition to 
the characteristic of being an ordered group, sometimes these groups also have an index to 
identify each position, that the index usually changed monotonically in v alue, and that the 
index of position 0 might be any value. The term Bus is used for these groups in which the 
positions are indexed. 

CONSTRAINT 

In spite of the fact that, for some systems, the distinguishing characteristic of a Bus from a Bundle is that it is indexed 
instead of having names for each position, the member Nets of a NetBus are also required to have names which arte 
unique with respec t to all Net names in the Owner NetiistView. This is because NetBusses are NetBundles which are 
Nets which have this constraint 
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Pfable of Contents Dprcvious Chapter 

4 Global Policy and Conventions 

This section describes those topics that concern the overall functionality of the programming interface. It 
outlines the decisions (or policies) about which functions are available in the interface, how they behave 
in general, and what limitations there might be. When appropriate, rationale is given for the policy so 
that the Design Representation Working Group (DR WG) can use the information in future discussions. 



4.1 Data Types 

This section discusses the information that is included in the cfidr.h header file which (1) must be 
included in any code using the DR-PI and (2) in turn includes cfi.h with the CFI-wide type definitions. 
See Ifl &D&idix B Stan dard Header Files" for listings of the standard cfidr.h and cfi.h files. 



4.1.1 Primitive Data Value Types 

Boolean Values 

typedef enum { 

CFIDR_FALSE - CFI_FALSE, 

CFIDR_TRUE = CFI_TRUE 
} cf idrBooleanT; 

NOTE: CFLJALSE and CFLTRUE are defined in cfi.h. 
32-bit Integer Values 

#define CFIDR_J*AX_INT32 2147483647 
#define CFIDR_MIN_INT32 -2147483647 



typedef cfiLongT cf idrInt32T; /* defined in cfi.h */ 
32-bit Floating Point Values 

#define CFIDR_MIN_FLOAT32 -1E+37 
#define CFIDR.JiAX_FIiOAT32 1E+37 



typedef cfiFloatT cf idrFloat32T; /* defined in cfi.h */ 

Character Strings 

typedef cfiStringT cf idrStringT; /* defined in cfi.h */ 

Void Return Values 
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typedef cfiVoidT cfidrVoidT; /* defined in cfi.h */ 
Object Identifiers 



typedef 
typedef 
typedef 
typedef 
typedef 
typedef 
typedef 
typedef 
typedef 
typedef 
typedef 
typedef 
typedef 
typedef 
typedef 
typedef 
typedef 
typedef 
typedef 
typedef 
typedef 



cf iObjectldT 

cfidrObjectldT 

cf idrObjectldT 

cfidrObjectldT 

cfidrObjectldT 

cfidrObjectldT 

cfidrObjectldT 

cfidrObjectldT 

cfidrObjectldT 

cfidrObjectldT 

cfidrObjectldT 

cfidrObjectldT 

cfidrObjectldT 

cfidrObjectldT 

cfidrObjectldT 

cfidrObjectldT 

cfidrObjectldT 

cfidrObjectldT 

cf idrOb j ec t IdT 

cfidrObjectldT 

cfidrObjectldT 



cfidrObjectldT; /* defined in cfi.h */ 
cfidrNamedObjectldT; 
cfidrLibldT; 
cfidrCellldT; 
cfidrPortldT; 
cfidrPortBundleldT; 
cfidrPortBusIdT; 
cfidrPortScalarldT; 
cfidrlnstldT; 
cfidrPortlnstldT; 
c f i dr Port Ins t Bundl el dT ; 
cf idrPortlnstBusIdT; 
cfidrPortlnstScalarldT; 
cfidrNetldT; 
c f idrNe tBundleldT ; 
cfidrNetBusIdT; 
cfidrNetScalarldT; 
cf idrPropIdT; 
cfidrViewIdT; 
cfidrEncapsulatedViewIdT; 
cfidrNetlistViewIdT; 



Iterator Identifiers 



typedef 
typedef 
typedef 
typedef 
typedef 
typedef 
typedef 
typedef 
typedef 
typedef 



cf ilteratorldT 

cfidrlterldT 

cf idrlterldT 

cfidrlterldT 

cfidrlterldT 

cfidrlterldT 

cfidrlterldT 

cfidrlterldT 

cfidrlterldT 

cfidrlterldT 



cfidrlterldT;/* defined in cfi.h */ 
cf idrCellsIdT; 
cf idrlnstsIdT; 
cfidrLibsIdT; 
cfidrNetsIdT; 
cf idrNetBundlesIdT; 
cf idrPortsIdT; 
cf idrPortlnstsIdT; 
c f idr Props IdT ; 
cf idrViewsldT; 



4.1.2 Enumerated Constants 

Types of Objects 

typedef enum { 



= 


o, 


CFIDR_UNDEFINED_OBJECTTYPE 




1, 


CFIDR_LIB 




2, 


CFIDR^CELL 




3, 


CF I DR_PORTBUNDLE 




4, 


CFIDR^PORTBUS 




5, 


CFIDR_PORTSCALAR 




6, 


CFIDR_INST 




7, 


CFIDR_PORTINSTBUNDLE 




8, 


CFIDR^PORTINSTBUS 


s 


9, 


CFIDR_PORTINSTSCALAR 




10, 


CFIDR-NETBUNDLE 




11, 


CFIDRJIETBUS 
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= 12, CFIDRJJETSCALAR 
= 13, CFIDR^ROP 
= 14, CFIDR^NETLISTVIEW 
= 15, C F IDR_ENCAP SULATEDVI EW 
= 16 CFIDRJMAX^OBJECTTYPE 
} cf idrObjectTypeT; 

Types of Views 

The string "CFIDIU^rETLISTVIEW ,, is reserved as the value of the ViewType attribute for views of 
type cfidrNetlistViewIdT. The cfidrObjectGetObjectTypeO function can be used to distinguish 
between the NetlistView and EncapsulatedView types. 

Types of Values 

typedef enum { 

CFIDR_UNDEFINED_VALUETYPE = CFIJUNDEFINED_VALUETYPE, 

CFIDR_INT32 = CFIJUONG, 

CFIDR_STRING = CFI_STRING, 

CFIDR W FU)AT32 = CFI_FLOAT, 

CFIDR_BOOLEAN = CFI_BOOLEAN, 

CFIDR^1AX_VALUETYPE 
} cfidrValueTypeT; 

NOTE: All the values for the right hand sides above starting with CFI_... are defined in cfi Jl 

Types of Port Directions 

typedef enum { 
= 0, CFIDR_UNDEFINED_PORTDIRECTION 
= 1, CFIDR_INPUT 
= 2, CFIDR_OUTPUT 
= 3, CFIDR_IO 

= 4 CFIDRJMAX_PORTDIRECTION 
} cfidrPortDirectionT; 

Types of Attach Modes 

typedef enum { 

= 0, CFIDR_UOTEFINED_ATTACHMODE 

= 1, CFI DR_ATTACH_BY_ORDER 

= 2, CFIDR_^TTACH_BY_JSAME 

= 3 CFIDR_MAX _ATTACHMODE 
} cfidrAttachModeT; 

Types of Access Modes 

typedef enum { 

= 0, CFIDR^UNDEF INED_ACCES SMODE 

= 1, CFIDR_READ 

= 2, CFIDIUUPDATE 

= 3 CFIDR_MAX^ACCESSMODE 
} cf idrAccessModeT; 

Types of Iterator Modes 
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typedef enum { 
= 0, C F I DR_UNDEF INED_I TERMODE 
= 1, CFIDR_ITER_SCALARS 
= 2, CFIDR_ITER_BUNDLES 
= 3, CFIDRJTERJTOP 
= 4, CFIDR^ITER^ALL 
= 5 CFIDR_MAX_ITERM0DE 

} cfidrlterModeT; 



Types of Errors and the Error Text 



The following table lists possible error codes in numerical order along with the conditions under which 
this error is to be returned. Also shown is an example of the text that could be returned by the 
cfidrPIGetErrorText function. However, the exact wording of the text may be left to the implementor. 



Table 1: Error Codes 



Types of Errors 



Example Error Text 



typedef enum { 

CFIDR_N0_ERROR =0, 

CFIDR_DESCRIBER_PORT _JIOT_FOUND = 1 , 

CFIDR_DESCRIBER_RECURSION =2 , 

CFIDR_DESCRIBER_VIEW_NOT_FOUND =3 , 

CFIDR_INTERNAL_SYSTEM_ERROR =4 , 

C F I DR_INVAL I D_ATTACH _#ODE =5 , 

CF IDR_UNUSABLE_DESCRIBER_OXD =6 , 

C F IDR_INVAL I D_DESCR I BER_TYPE =7 , 

CFIDR_INVALID_DIRECTION =8 , 

CFIDR_INVALID_ERROR_CODE =9 , 

C F I DR_ I NVAL I D_V ALUE =10, 

CFIDR__INVALID_ITER =11, 

CFIDR_INVALID_ITER_TYPE =12 , 

CFIDR_INVALID_MEMBERS =13 , 

CFIDR_INVALID_NAME =14, 

CFIDR_INVALID_OBJECTTYPE =15, 

CFIDR_UNUSABLE_OID =16 , 

CFIDR_UNUSABLE_PORT_OID =17, 



cfidrStringT cf idrErrorText [] = { 
'No error occurred." 
•Describer Port associated with 
Portlnst not found. 0 
■Describer would recursively 
instantiate a view." 
•Describer View associated with 
Inst not found." 

•Internal error occured in system 
implementing PI . ■ 
■The attachment mode specified 
is out of the range of possible 
values . " 

"The Describer OID refers to an 

unusable object" 

"The Describer OID refers to an 

object that is not a view", 

•The Direction is not a valid Port 

Direction. " 

■The Error Code constant 
specified is out of the range of 
possible values . ■ 

"The Value specified is out of the 
range of possible values." 
■The Iterator ID refers to a non- 
existent iterator." 
■The Iterator ID refers to an iter 
ator over the wrong object type." 
•Member is not a valid array of 
member names" 

•Name is not a valid string or 
contains illegal characters." 
"The type of object specified 
cannot be handled by the 
function. " 

"The Object ID does not refer to 
a usable object." 
•The Port OID does not refer to a 
usable object. ■ 
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CFIDR^INVALID_PORT_TYPE =1 8 , 

CFIDR_UNUSABLE_PORTINST_OID =19 , 

CFIDR_INVALID_PORTINST_TYPE =2 0 , 

CFIDR_INVALID_VIEWTYPE =21, 

CFIDR__LIB_ALREADY_OPEN =22 , 

CFIDR_NEW_DESCRIBER_PORT_FOUND =23 , 

CFIDR_NO_NAME_MATCHES =24, 

CFIDR_NAME_IN_USE =2 5 , 

CFIDR_OBJECT_ALREADYJBXISTS =26 , 

CFIDR_OBJECT JIOT_FOUND =27 , 

CFIDR_PORTINST^ALREADY_ATTACHED =2 8 , 

CFIDR_PORTINST_NOT_ATTACHED =2 9 , 

C F I DR_PORT_ALREADY_ATTACHED =3 0 , 

CFIDR_PORT_tfEMBERS_DIFFER =3 1 , 

C F I DR_PORT_NOT_ATTACHED =3 2 , 

C F IDR__VI EW_ALREAD Y_0 P EN =33 , 

CF IDR_OPEN_FOR_UPDATE_FAILED =3 4 , 

CFIDR_INVALID_ITERMODE =3 5 , 

CFIDR_ILLEGAL_OPERATION =36, 

CFIDR_CROSS_VIEW_OPERATION =3 7 , 

CFIDR_SCALAR_BUNDLE_ATTACHMENT =3 8 , 

CFIDR_LIB_OPEN_FAILED =3 9 , 

CFIDRJVTEW_0PEN_FAILED =40, 

CFIDR^INVALID^ACCESSMODE =4 1 , 

CFIDR_READ_ONLY =42, 



■The Port OID refers to an object 
that is not a usable Port." 
"The Portlnst OID does not refer 
to a usable object." 
•The Portlnst OID refers to an 
object that is not a usable 
Portlnst . " 

"The ViewType specified is not a 
legal string or is the string 
reserved for the NetlistView. ■ 
"The library specified is already 
open. " 

"A Port exists on the Describer 
View that does not exist as a 
Portlnst . " 

"No matches were found 
between the Scalar names when 
trying to attach . " 
"An object with the same name 
already exists in this 
namespace. " 

"The object that would be 
created already exists in the 
applicable scope." 
"The desired object could not be 
found. * 

"The Portlnst is already attached 
to a Net - it cannot be connected 
again . " 

■The Portlnst specified must be 
attached in order to be 
detached." 

•The Port is already attached to a 
Net - it cannot be connected 
again. • 

■The Describer Port members 
differ from associated Portlnst 
members . " 

■The Port specified must be 
attached in order to be 
detached. " 

■The View specified is already 
open. • 

•Opening the object in update 
mode failed. ■ 

•The IterMode specified is out of 

the range of legal values." 

■The attempted operation is not a 

legal operation." 

■Cannot connect objects not in 

the same view. " 

■Cannot attach bundles to 

scalars . " 

"The library could not be 
opened . " 

■The View could not be 
opened. " 

"The Access Mode specified is 

out of the range of legal values . " 

■The containing entity (library or 
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CFIDR_INVALID_KEY =43 , 

CFIDR_INVALID _NET_TYPE =44 , 

CFIDILJNVALID_PORTBUNDIiE_TYPE =45 , 

CFIDR_INVALID_POSITION =46 , 

CFIDR_MEMBER_RECURSION =47 , 

CFIDR_MULTIPLE_VIEWS_MATCH =4 8 , 

CFIDR^NO^VIEW^MATCHES =49, 

C F I DR_UNUS ABLE_J*ET_0 1 D =50, 

CFIDR_UNUSABLE_PORTBUNDLE_OID =51, 

CFIDR_MAX_ERROR =52 
} cfidrErrorT; 



View) has not been opened for 
update. " 

°Key is not a valid string or 
contains illegal characters." 
■The OID is not of type net." 
■The OID is hot of type 
portbundle. w 

■The position is not in the range 
0 to one less than the size of the 
bundle' 

•The Bundle would contain itself 
or a sub-bundle of itself as a 
member . w 

•There are multiple views of the 
same name in the same library or 
multiple views of the same type 
in the same library. • 
•No matches were found for 
views meeting the view selection 
criteria specified by the 
selectorSet." 

•The Net OID does not refer to a 

usable object. ■ 

•The PortBundle OID does not 

refer to a usable object." 
■ » 

}; 



4.2 Object Identifiers 

The Design Representation Programming Interface functions refer to objects described by the 
information model (IM) by using object identifiers (or OIDs). An OID references a unique occurrence of 
an entity type defined in the IM. For example, each specific Library is acted upon using PI functions that 
are supplied with its OID. As another example, each Net owned by a particular View will have a unique 



4.2.1 OIDs Are Abstract Data Types 

Policy: Users of the DR-PI must treat OIDs as an abstract data type. Nothing can be assumed about their 
implementation. 

Rationale: The application cannot assume what the OID represents. In the long-term, the DR Working 
Group needs to understand if and how systems with differing OID lengths can be interoperable in a CFI 
framework. 

NOTE: In CFI DR 1 .0, OIDs are a fixed size for any given binary instruction set machine architecture 
and specified to be twice the size of an address (void *). However, do not assume that the OID is a 
structure containing two addresses even though that is the correct size for it. 



4.2.2 OIDs Are Scoped Per Session 
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Policy: OIDs are valid for the current PI session. A session is defined as the interval of time which starts 
when the PI is initiated with a call to cfidrPIInitO and terminates when you dismiss the PI with a call to 
cfidrPIQuitO. Tbw, OIDs are not persistent across multiple invocations of the PL Also, the OID 
assigned to an object in one invocation cannot be assumed to be assigned to the same object in the next 
invocation. 



4.2.3 OIDs Are Scoped by Open/Purge and Destroy 

Policy: In addition to the lifetime of OIDs being limited to the PI session, the lifetime of OIDs is also 
limited by the open/purge operations (whose policies are described later) as well as by destroy 
operations. Thus, when an OID comes into existence via an open, it remains usable as a reference to the 
object until the object is purged or destroyed. 

Rationale: The PI allows for creation, modification, and destruction as well as data retrieval. The DR 
Working Group also notes the need to incorporate the notion of opening, saving, and purging of data. 
The lifetime of OID usability must fit into these additional operations. 



4.2.4 OIDs for Supertypes (Allow Polymorphism) 

Policy: The Information Model defines a class hierarchy of entity types. The class hierarchy is defined 
by supertypes and subtypes. Some of the supertypes are ABSTRACT but the only objects which can 
actually be created are the non-abstract types, most of which have no further subtypes. The only 
exception is that each of the Bundle types (Net, Port, Portlnst) can be created although each is also a 
supertype of a corresponding Bus, which can also be created. However, even though most supertypes 
can not be directly created, some PI functions are defined which accept OIDs of those supertypes in the 
IM. The important fact is that a supertype OID can refer to objects of any of the supertype's subtypes (or 
subtypes of those types). 

For example, cfidrPortldT is the OID of a supertype. Since the Port supertype specializes into 
PortBundle and PortScalar subtypes, a cfidrPortBundleldT or cfidrPortScalarldT can be passed to any 
function that takes as input a cfidrPortldT. Furthermore, since a cfidrPortBusIdT is the OID of a PortBus 
which is the subtype of a PortBundle so it can also be passed to any of the functions that require 
cfidrPortBundleldT for the type of an argument. 

Likewise, a function declared to return a cfidrPortldT can can also return a cfidrPortBundleldT, 
cfidrPortBusIdT, or a cfidrPortScalarldT. A call to cfidrObjectGetObjectTypeO will return the lowest 
subtype of object given any OID (i.e., it takes as input the cfidrObjectldT). 

Rationale: One way to reduce the number of functions generated by the PI is to define OIDs which may 
be of several different object types. Allowing OIDs to refer to supertypes is the natural way to do this. It 
allows a very object-oriented polymorphism in the PI functions. 



4.2.5 Checking for the Same Object 

Policy: There is no requirement that a given object only have one OID. Therefore a function is provided, 
cfidrObjectlsSameO, which determines whether two OIDs refer to the exact same object. This is the 
only mechanism that an application using the PI can use to determine this condition. 
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Rationale: Using an operator such as is not valid since the OID is an abstract data type. 
Furthermore some implementations use more than one ODD for the same actual object. This test for 
sameness must be performed by the implementation of the PI which knows what objects the OIDs are 
actually referencing. 



4.2,6 Checking for a Usable Object ID 

Policy: A function exists, cfidrObjectlsUsableO, which determines whether an OID is usable (i.e., 
refers to an existing object). This is the only mechanism that an application using the PI can use to 
determine this condition. An OID may become unusable if the object to which it is referring has been 
purged or destroyed. 

Rationale: Since the application must treat the OID as an abstract data type, nothing can be inferred 
about the OIDs value and whether it refers to an existing object or not. This function allows testing for 
"dead" OIDs that no longer reference a usable object 



4.2 .7 Checking for a Null Object ED 

Policy: A function exists, cfidrObjectlsNullO, which determines whether an OID is the Null OID. A 
Null OID is not usable (i.e., it does not refer to an object), but it is valid as an OID. Null OIDs are 
returned to the application primarily when an error of some sort occurs during execution. This function 
is the only mechanism that an application using the PI can use to determine whether an OID is Null. 

Rationale: Since an OID is an abstract data type, nothing can be inferred about what constitutes a Null 
OID. 

Policy: There must be only one unique representation of a Null OID per session. 



4.2.8 Iterator IDs Are Not OIDs 

Policy: Many attributes in the information model represent one-to-many relationships. Functions in the 
PI returning objects that participate in the "many" side of the relationship are done via returning a 
Iterator ID. Iterator IDs are not OIDs in the sense that they do not refer to actual design objects in the 
database. By using functions beginning with "cfidrlterNext../ the objects traversed by the Iterator are 
returned one at a time. Also, each time a one-to-many relationship is traversed, a unique Iterator is 
created. Thus, several independent traversals can be made over the same relationship, each traversal 
uniquely identified by its own Iterator ID. 

NOTE: The Iterator "objects" are used to traverse both SETs and LISTs as specified by EXPRESS. SETs 
have no significant order while the order of LISTs is significant. 



4.3 Error Handling 



h 



43.1 Error Handling Supports Functional Programming Style 
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Policy: Error handling in the DR-PI supports a ftmctional programming style instead of a procedural 
programming style. Thus, the normal return value of functions is the data being sought, e.g., an OID, an 
integer, a string, etc. The return value often does not indicate that an error has occurred. In some cases 
that is because there is no illegal value in the range of possible return values. Hence the user should 
always check the error return parameter to determine if an error has occurred. 



4.3.2 Error Code Output by Each Function 

Policy: A pre-defined error code type is defined for the DR-PI. A pointer to a variable of this type is 
required as the last argument of each function in the PI. The argument is passed-by-reference (i.e., the 
address of the variable is supplied) and is output from each function. Each function description 
enumerates a list of possible error codes returned. 

Rationale: The Specification Standards Working Group (SSWG) recommended defining the error code 
as an output of each function so that the functional interface style can be accommodated. Also, by 
forcing the error code to be output as a specific argument with each function, it will hopefully provide 
incentive for applications to check the error code. This checking was commonly bypassed when a global 
error code was used. 



4.3.3 Pre-defined Error Code Text Available 

Policy: Each error code will have pre-defined text associated with it. The application may wish to 
enhance this error text with information specific to the context in which the error occurred. 

Rationale: Pre-defining the error text relieves the application of creating error messages when the pre- 
defined text is sufficient. 



4.4 Names and Strings 



4.4.1 Characters in Names Have No Semantics 

Policy: There are NO SEMANTICS associated with any names or the characters used in them. Thus if a 
NetBus has a Name attribute "ADDRT3 1 :0] n it may NOT be assumed that the Start attribute is 3 1 or that 
Ae derived Width attribute is 32 or that the Step attribute is -1 . Also, an implementation should not 
interpret 7", "V, or (or any other characters) as file system directory name separators. 



4.4.2 Character Set for Name Strings is Restricted 

Policy: The valid character set for objects having a Name attribute is: 
• The Printable ASCII character set 

Bp ! "#$%&' 

( )* + ,-./ 

01234567 
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No other characters are allowed to be part of the Name attribute. Any fraction which takes a Name 
attribute as input for creation or modification must check to ensure this policy is upheld. 

Note that Null strings (" ") are legal input parameters to certain ViewSelection functions. 



4*4*3 Character Set for Other Strings Is Unlimited 

Policy: For any other object attribute which is a string, there is no limitation on which characters 
comprise the string other than that the string be delimited with the Null character (i.e., AO 1 ). 

Rationale: Since a string is just a character array and each character is at least an 8-bit structure, the 
application may store any bit sequence in the memory which constitutes the character. Thus, fee 
character array may be comprised of any binary sequence, as long as it is delimited by the Null 
character. 



4.4.4 String Comparison Is Case-Sensitive 

Policy: For all strings (especially those referring to Name attributes), the application must treat 
comparison of the strings as case-sensitive. 

Rationale: Since case-sensitive strings can be added, it is consistent to expect their comparison to also be 
case-sensitive. 

NOTE: It is strongly recommended that unique names differ in other than just case. 



4.4.5 A String's Maximum Length Is Not Defined 

Policy: There is no defined limitation for the length of a string. 

Rationale: There was no one maximum length on which the Working Group participants could agree. 
Some implementations of the PI will be unable to support unlimited lengths. An implementation will 
return an error code denoting a system-dependent failure if a string exceeds the capacity of that system 
and this is detectable by the implementation. 



4.4.6 Strings Supplied to Functions Are "Stored" 



Policy: The memory pointed to by a string (i.e., char *) that is passed into a PI function must remain 
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valid until the function has exited. After the function has exited it may then be changed without affecting 
the data "stored" by the PL 

For example, the function cfidrPropSetStringO value must be supplied a pointer to a string as the value 
argument. The memory pointed to by this argument should not be changed until after the function has 
exited. However, this memory may then be changed without affecting the "stored" value for the string. 
Specifically, if the cfidrPropSetStringO has exited, then the memory that was pointed to is changed, and 
then cfidrPropGetStringO is called (on the same Prop object), the value returned by cfidrPropGetString 
0 will be the same as that supplied to the last call to cfidrPropSetStringO. 

Rationale: This prevents the user of the DR-PI from having to create separate storage for every unique 
string ever created. It presumes the provider of the DR-PI has a place to store these values. 



4.4.7 Strings Returned May All Be in One Buffer 

Policy: The memory pointed to by a string that is returned by a PI function is only guaranteed to remain 
valid until the execution of another PI function which also returns a string or until the function 
cfidrPIQuitO is called. 

For example, if cfidrNamedObjectGetNameO returns a string representing the Name attribute of an 
object, that string remains valid until the next call to a DR-PI function returning a string, which might be 
cfidrNamedObjectGetNameO, or cfidrPropGetStringValueO (gets a property's string value), or any 
other function returning a string. Calling cfidrPropGctBoolean ValueQ would not invalidate the Name 
since that function returns a Boolean. 

Rationale: This allows the provider of the DR-PI to use one string buffer for the return of all strings. It 
requires the user of the DR-PI to make a copy of any string that will still be needed before making a call 
to another string-returning DR-PI function. 

However, while it is not required that a PI provider use more than one buffer in which to return strings, 
it is recommended that at least several (say 10) of the most recently returned strings remain valid in spite 
of another string-retuming call. This allows for the possibility of a user failing to copy a needed string 
before calling a second string-returning PI function. 



4.5 Persistency Behavior (Open / Save / Purge) 



4.5.1 Open/Save/Purge Operate Only on Libraries and Views 

Policy: The operations of open, save, and purge are applicable only to Library, View, and SelectorSet 
objects. Thus, the functions implementing these operations should only accept input that defines 
Libraries, Views, or SelectorSets. 

Rationale: Since the PI has to deal with creation, modification, and destruction, that means it is also able 
to persistently deal with object data. Also, the DR Working Group notes that open, save, and purge are 
generic operations that apply to any information model. 

An arbitrary decision was made to define which objects these operations acted on. The decision was 
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based on Views being the smallest unit that may be opened. Libraries were the highest level. Cells were 
not included because of the behavior of open (see below). SelectorSets are equivalent to Libraries with 
respect to persistence behavior of View Selection objects. They have no owner but own all of the 
Selectors "below" them. 

It is expected that in the future, these operations will be replaced by operations provided by a generic 
CFI standard for data management. 



4.5.2 Description of Open Behavior 

Open Makes Objects Available 
Policy: The open operation makes available the desired object. 

Rationale: The term "makes available" is deliberately used so as not to put any requirement on whether 
the object is made available by bringing it into memory at the time of open or by leaving it on disk until 
the object is referenced. 

Open Recursively Walks Ownership Hierarchy 

Policy: In addition to making available the desired object, open makes available all the objects in the 
ownership hierarchy until another object is reached that must be opened individually (i.e., has its own 
open function). 

Consider the Information Model and take into account the policy that only Libraries and Views can be 
opened. Opening a Library not only makes the Library object available, but also all of its owned 
Properties, the Cells owned by Ihe Library, and the Cells' owned Properties. The Views owned by each 
Cell are not made available since Views must be opened by themselves. 

Opening a View makes the View object available as well as all its owned Properties, Nets, Insts, Ports, 
etc. 

Rationale: The policy was derived arbitrarily but a consistent and well-defined behavior is presented. 
Open Modes 

Policy: There are two defined modes for open: CFIDRJtEAD and CFIDR_UPDATE. CFIDR_READ 
allows for read-only access to a Library or a View. No Cells, Views, or Properties on Libs or Cells, can 
be created or deleted from a Library unless the Library is opened for CFIDRJJPDATE. An existing 
View may be opened for CFIDR_UPDATE even though it's owning Library is opened for 
CFIDR_READ. A Lib can be destroyed regardless of the access mode of any object. 

SelectorSets do not have an access mode, and they or their contents can be changed, purged, or 
destroyed regardless of the access mode of any object 

Until concurrence specifications are provided, the specification for open explicitly does not include 
support for multiple writers or multiple readers with a single writer. 

Automatically Opening Libraries 
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Policy: When attempting to open a View, if the owning Library is not opened already, an attempt to 
open it should be made. 

Rationale: This appears to be the appropriate thing to do instead of returning an error. 

Policy: When traversing a set of Libraries using the cfidrlterNextLibO function, if the Library is not 
opened already, an attempt to open it should be made. 

Automatically Opening Views 

Policy: Views are automatically opened in two different situations: (1) when traversing the list of Views 
owned by a Cell, and (2) when traversing the Describer relationship from an Inst to the View. 

Rationale: To reduce the number of functions, the automatic feature of opening views was defined as 
part of the traversal functions instead of defining separate functions for traversing just the Views opened 
as opposed to all Views. 

No Automatic Creation of Libraries and Views via Open 

Policy: If an attempt to open a non-existent Library or View occurs, the open function returns an error. 
The Library or View is not created automatically. 

Rationale: If the creation were automatic, the only way to determine whether the Library or View exists 
already is to iterate through the list of Libraries or Views looking for the one in question. This policy 
makes the application create the Library or View explicitly if it does not exist 



4.5.3 Description of Save Behavior 

Save Makes Changes Persistent 

Policy: The save operation synchronizes the persistent version of data on disk with any changes made to 
that data since the last save or open. This behavior pertains to destruction as well as creation and 
modification; however, destruction of the persistent copies of libs, views, or selector sets occurs 
regardless of any save. All OIDs of objects saved remain usable and unchanged after the save. 

Save Walks Ownership Hierarchy 

Policy: Similar to open, save also recursively walks the ownership hierarchy of objects rooted by the 
specified object and saves all the objects in this hierarchy. Unlike open, save continues walking the 
ownership hierarchy when it encounters an object which can be saved individually. 

Consider the Information Model and take into account the policy that only Libraries and Views can be 
saved. Saving a View updates the persistent version of the View and its Nets, Ports, Insts, and Props. 
Saving a Library not only saves the Library and Cells, it also saves all the Views as well 

Rationale: When opening a Library, opening all the Views automatically is probably undesirable in most 
situations. However, when saving a Library, saving all the Views and thus taking a "snapshot" of the 
Library at that instant is most desirable. If necessary, the application can save each View individually. 
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4.5.4 Description of Purge Behavior 

Purge Removes Changes 

Policy: The purge operation removes any changes made to an object since the last save or open. The 
object then becomes unavailable and its OID becomes unusable. Opening the object again assigns the 
object an OID and makes it available for updating. 

An example implementation that would provide this behavior would make an in-memory copy of an 
object. All changes would be made against the in-memory copy of the object. If that object is then 
"purged," the copy of the object is deleted from memory, leaving the original, on-disk copy unchanged. 

A lib, view, or selector set may be purged at any time, unrelated to access mode. 

Purge Walks Ownership Hierarchy 

Policy: Similar to open, purge also recursively walks the ownership hierarchy of objects rooted by the 
specified object and purges all the objects in this hierarchy. Unlike open, purge continues walking the 
ownership hierarchy when it encounters an object which can be purged individually. Thus, purge 
behaves similarly to save in this respect 

Consider the information model and take into account the policy that only Libraries and Views can be 
purged. Purging a View removes the View's objects (Nets, Ports, Insts, and Props). Purging a Library 
not only purges the Library and Cells, it also purges all the Views as well. 

Rationale: When opening a Library, opening all the Views automatically is probably undesirable in most 
situations. However, when purging a Library, it does not make sense to only purge the Library and Cells 
and not the Views. 



4,5.5 No Close or Revert Operations 

Policy: No functions to close or revert Libraries and Views are specified for the DR-PI. 

Rationale: Although the DR Working Group discussed close and revert operations, no agreement was 
reached as to their detailed behavior — especially with close. If revert means to refresh the current 
objects available with their persistent definition, this can be modeled using purge followed by open. 



4.6 Library Functionality 

Multiple Libraries May Be Open at the Same Time 

Policy: Multiple libraries may be open at the same time, thus allowing NetlistViews to have instances of 
NetiistViews contained in other libraries than themselves. 

Libraries Retained Across Session Boundaries 
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Policy: After creating and saving a Library, the DR-PI retains the Library across session boundaries. 
Thus, the Library may be subsequently opened and updated in a future session. 

Rationale: Hopefully this is obvious since persistency of the data is a primary goal of any database. 
OIDs, however, do not persist across sessions. 

No Knowledge of Storage Hierarchy 

Policy: The application using the PI requires no knowledge of the storage hierarchy with respect to 
where and how Libraries are contained in this hierarchy. The application sees Libraries only by the 
names given to the Library at creation. 

Rationale: Each implementation of the PI probably has its own internal mapping of a Library onto a 
storage hierarchy. This system-dependent behavior should be bidden completely from the DR-PI user. 



4.7 Effects of the Ownership Hierarchy 

The ownership hierarchy plays an important part in the IM and is used by many of the PI functions. The 
creation functions define what object owns another. The cfidrCellGetOwnerO, cfidrlnstGetOwnerO, 
cfidrNetGetOwnerO, cfidrPortGetOwnerO, cfidrPortlnstGetOwnerO, cfidrPropGetOwnerO, and 
cfidrViewGetOwnerO functions return an object's owner. The traversal of an object to all of the objects 
it owns constitutes one level of the ownership hierarchy. By starting at a Lib and recursively traversing 
to all owned objects, all design objects "in" that library will be visited at least once. 



4.7.1 Open I Save / Purge Uses Ownership Hierarchy 

As stated previously, the functions dealing with persistency (open, save, and purge) each work as though 
traversing down some or all of the ownership hierarchy. See the discussions of these policies for more 
details. 



4.7.2 Destroy Uses Ownership Hierarchy 

Policy: Similar to open, destroy also recursively walks the ownership hierarchy of objects rooted by the 
specified object and destroys all the objects in this hierarchy. Unlike open, destroy continues walking 
tiie ownership hierarchy when it encounters an object which can be destroyed individually. Thus, 
destroy behaves similarly to save and purge in this respect. 

NOTE: The term destroy is used instead of delete to emphasize that the object is removed entirely and 
not just disconnected from all relationships in which it participates. 

Rationale: It would not make sense, for example, when destroying a View, that the owned Nets, Insts, 
etc., are left An object cannot exist without an owner. 



4.8 "Describes" / "WhereUsed" Is Not Required 
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Policy: The inverse of the Describer attribute for Insts, sometimes called Describes or WhereUsed is 
neither specified in the IM nor available via a DR-PI function. 

Rationale: This relationship cannot be fully maintained in general. 

For example, consider a NetlistView "A" with an Inst "bP of NetlistView "B". Suppose this is done, 
then "A" is stored, "B" is stored elsewhere, and then the storage media on which "A" resides is 
physically destroyed (or just taken off-line). An attempt of "B" to keep "bl" on a Describes attribute will 
result in a dangling reference because "bl " no longer exists (in the system). 

For another example, consider a widely used "primitive" such as a basic Inverter. The WhereUsed list 
for this item could become extremely long— easily in the millions! If not impossible, it is generally 
unreasonable to require an implementation to keep track of all these uses. 

NOTE: this neither precludes nor forbids a particular implementation from maintaining Describes or 
WhereUsed information for as broad of context as reasonable (usually all designs open in a session). 



4.9 "Describer" / "Describes" Modification Behavior 



4.9.1 Modification on "Described" Objects Disallowed 

Policy: The DR-PI disallows any modifications to Described objects (i.e., Insts and Portlnst) with 
respect to data derived from the Describers (Views and Ports respectively). 

Thus, an Inst's Name attribute may change since it is defined only for the Inst However, the Inst's 
Describer relationship cannot be updated. Likewise, a Portlnst's DescriberName and DescriberDirection 
attributes cannot be modified since they refer to information derived from the Describer Port. 

Rationale: Restricting the modifications simplifies issues of consistency between the Describer object 
and what it Describes. These limitations will be revisited in future versions of the DR-PI. 



4.9.2 Limited Updates on "Describer" Allowed 

"Describes" Object Not Affected by "Describer" Creation 

Policy: Describer objects can be created without any affect on Describes objects that might otherwise 
know about the new Describer objects. 

For example, creating another Port in the Ports of a NetlistView does not automatically add the 
appropriate Portlnst to the Portlnsts of any Inst whose Describer is this NetlistView. 

Rationale: Limiting creation of Describer objects until they are first instantiated is impractical without 
full support of the Describes relationship. That some of the described Views may not even be opened (or 
openable!) complicates this issue even further. 

Destroying "Describer" Invalidates "Describer" Object Relationship 
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Policy: When a Describer object is destroyed, the Describer relationship referencing it becomes invalid. 

For example, destroying a NetlistView means that any Inst referencing that NetlistView via the 
Describer relationship must return a Null OID when traversing this relationship. The actual time at 
which the relationship is broken depends on the implementation. It may happen at the time of 
destruction, when opening the NetlistView owning the Inst, or when attempting the traversal. 

Rationale: The only way to avoid defining this behavior is to disallow destruction. Allowing destruction 
of the Describer objects at the minimum means that trying to reference the Describer objects should fail. 

Updating "Describer- Attributes Not Allowed 

Policy: Analogous to not allowing modification of Describes objects, the PI disallows any updates to 
Describer object attributes. 

Thus, for example, once a NetlistView is created, its Name may not change. The same is true for Port 
attributes. 

Rationale: This limitation helps reduce the number of issues surrounding consistency between Describer 
and Describes objects. 

However, describer attributes (including names of ports, their directions, start/step values, even to what 
nets they are connected) might implicitly be changed in server implementations that allow describer 
relationships to be re-established automatically "by-name" when a describer is destroyed and then re- 
created. (See "Re-Establishing Describer Relationships" below). 

Re-Establishing Describer Relationships 

There are currently no requirements or limitations with regard to re- establishing describer relationships 
with Insts after their describers have been destroyed. A server (CFI DR provider) is free to consider new 
view/port oids, created subsequent to the destruction of describer views/ports, as "replacement" 
describers. Naturally, since recreation of describers might result in differences in the number, names, 
attributes, attachments, or properties of objects in the view, a server must make clear the details of 
functionality in all possible cases that might occur. 

Alternatively, a server is under no obligation to re-establish such "by-name" relationships, and may even 
forbid it completely, putting the burden of destroying and recreating all affected Insts solely on client 
applications. 

Each server will document its own rules for describer relationship behavior. A client application may 
need to be aware of the differences among server implementations that could affect its operation and 
interoperability with other server implementations. 

Functions to Check Consistency 

Policy: To make it easier to determine whether an Inst or Portlnst is out-of-date regarding its Describer 
View or Port, specific functions exist in the DR-PI: cfidrlnstCheckDescriberO and 
cfidrPortlnstCheckDescriberO. 

Rationale: Rather than putting the burden on the application to determine this fact, a specific PI function 
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helps isolate the checking and make the determination more uniform across applications and PI 
implementations. 



4.10 Limitations During One-to-M any Relationship Traversal 



4.10.1 No Add/Destroy During List or Set Iteration 

Policy: The application should not add or destroy any objects that participate in a List or Set when 
actively iterating over the objects in that relationship (via functions such as cfidrlterNextCellO, 
cttdrlterNextNetO, etc.). Adding or destroying objects has an undefined effect on whether the object 
shows up (or does not) during iteration. 

Rationale: The DR Working Group has not resolved the details of adding/destroying with respect to 
active iterators other than determining that these operations cannot be done at all during active iteration. 



4*11 Limitations on Top-Down Designing 



4.11.1 Top-down Creation 1$ Not Directly Supported 

Policy: When creating an Inst, the Describer NetlistView must already exist. Portlnsts on the Inst are 
only created corresponding to the Ports on the Describer NetlistView. Thus, the DR-PI discourages and 
provides no direct support for top-down designing. 

Rationale: The details of doing top-down design have not been resolved including what propagation of 
changes from Ports to Portlnsts is necessary or desirable. 

NOTE: It is possible to fake the appearance of top-down design by hiding the creation of a NetlistView 
for use as the Inst's Describer during the apparently (to the user) direct creation of the Inst. Then, to 
modify the Portlnsts of the Inst, Ports are modified on the hidden Describer NetlistView and the Inst is 
deleted and re-created. Since this requires the tool to remember any Net to Portlnst attachments, delete, 
and then re-create them, it is not an ideal way to do top-down design, but it is possible. 



4.11.2 Creating an Inst Creates Portlnsts 

Policy: When creating an Inst, all of the Ports in the Describer View are automatically created and made 
available as Portlnsts owned by the Inst. This is the only way that Portlnsts are created. 

Rationale: Rather than forcing the application to create each Portlnst directly, the DR-PI does this work 
automatically. Also, the DR-PI wants to enforce as much consistency as possible between the Inst and 
its Describer View. 



4.12 Limitations on Searching Functions 
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4.12.1 Search / Query Functions Are Only Defined For Names 

Policy: Other than a simple set of cfidrFind...ByName() functions, the DR-PI does not define functions 
to search and find an object given one of the object's attributes. 

Rationale: This functionality can be completely implemented using the one-many relationship traversal 
functions (e.g., cfidrNetBundleGetNetsO, cfidrViewGetNetsO, and cfidrlterNextNetO). After 
iterating over an object, the application can do any necessary comparison checking. Thus, the DR-PI 
already supports the primitive functionality necessary. 

cfidrFind...ByNameO functions have been added because of the potential for speedup they provide, 
especially with network access to the DR-PI via Remote Procedure Calls. Furthermore, since names are 
required to be unique in each name scope, any implementor must already have internal functions to 
check for the pre-existence of a potential new name. Thus, providing this function as part of the defined 
CFI DR-PI interface is not difficult in general. However, these functions have been kept deliberately 
simple. Therefore, there are no functions defined at this time for case-insensitive name lookup, or for 
wild cards, or for regular expressions. 



4.13 Limitations on Object Creation 



4.13*1 Owner Always Specified 

Policy: Whenever creating an object, the PI creation functions require specification of the object's 
Owner. Thus, the PI disallows creating an object and assigning it an owner at some later time. 

Rationale: Most systems currently cannot handle creating an object without an owner. To do so usually 
requires this capability be modeled in the system in an unclean manner. For those systems allowing 
object creation without an owner, the PI limitation of specifying the owner at creation time just 
combines the creation and owner assignment into one step instead of two, separate disjoint steps. This 
behavior does not require any form of workaround. 



4.13,2 Inst/Portlnsts Do NOT Automatically "Inherit" Props 

Policy: Properties existing on the Describer NetlistView and its Ports are NOT inherited or 
automatically created on an Inst and its Portlnsts respectively during creation of that Inst. Specifically 
this means that when getting the Props of the Inst or Portlnsts, only those Props explicitly created on the 
Inst or Portlnst via the DR-PI are required to appear. 

Rationale: Not all systems automatically copy or can reference properties from the Describer when 
accessing the "Describee" Inst or Portlnst. For those that can, the Inst appears to have both the properties 
directly attached to it and those of the Describer NetlistView. The same is done for each Portlnst with 
respect to its Describer Port. The usual semantic is that, for a given name, that Prop on the Inst (or 
Portlnst) "overrides" any on the Describer. If this behavior is desired then, when looking for a Inst (or 
Portlnst) Prop, an application using the DR-PI should first get the directly attached Props. If the desired 
Property is not found, then the Describees Properties should be gotten. 
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4.14 Bundle/Scalar Manipulation 



4.14.1 Name Change Not Allowed for Attached or Bundled Scalars 

Policy: The DR-PI does not allow changing the Name attributes of Net or Port Scalars when they are 
contained in a bundle or already attached to a Port or Net 

Rationale: Name changes are not allowed since some implementations rely on the names to establish 
connectivity (and other relationships). In such systems changing the name can have side effects 
including changes in the circuit connectivity. 

As with most of the other bundle- and scalar-related limitations, this helps provide a consistent and 
simple approach for specifying the PI functionality. There is insufficient agreement in the DR Working 
Group on the fine grain behavior associated with allowing maximum editability, especially with respect 
to connectivity. Restrictions present now may be lifted at a later time when this behavior can be 
standardized. 

The DR-PI does now allow attach and detach connectivity operations on bundle members. In addition, 
changing bundle membership is allowed. 



4.14.2 Attribute Modification on Unconnected Bundle Only 

Policy: A bundle must be completely unconnected (i.e., all of the members unconnected) in order for 
any of the bundle's attributes to be modified. 

This includes modification of a Bundle's Name attribute via cfidrNamedObjectSetName() It also 
includes modification of the contents of the Bundle via cfidr...BundleCreate...Bundle/Bus(), 
cfidrNetBundlelnsert/RemoveNetO, and cfidrPortSetOwner...() 

Rationale: This condition simplifies specifying PI functionality regarding connectivity in the presence of 
incremental changes. 



4.143 NetBundle Connection to Port[Inst]Bundle is a Derived Relationship 

Policy: Only scalar connections (attachments) are explicitly made between the members of a NetBundle 
and a PortBundle or PortlnstBundle. Bundles are only ever connected when at least one member is 
connected and not simply because a function was executed to connect them. 

The functions that try to connect bundles by name or by position are really "power" operations that 
cause recursive traversal "down" the bundles looking for at least one scalar to connect. Then, if and only 
if a pair of scalars (one Net and one Port or Portlnst) are finally connected, do the bundles in which the 
scalars reside get connected. Because of this rule, a function call to attach a NetBundle to a Port[Inst] 
Bundle where these bundles are actually contained in higher level bundles can cause also attachments to 
recursively happen "above" the bundles being explicitly connected. 



The functions to disconnect bundles are also "power" operations looking for scalar connections with the 
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results of the scalar disconnections propogated "up" to any containing bundles possible causing bundle 
disconnections. 

Functions to destroy bundle members or change their owner (container, in the case of NetBundles) are 
also followed by a recursive analysis both "up" and "down" the bundle hierarchy to determine the 
resulting bundle connectivity. 
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5.1 Document Conventions 

The conventions used in this chapter are explained in the following sections. This includes the ordering 
of the function definitions, how function names are related to the information model, the font and style 
conventions, and the particular subsections used in the definition of each function. 



5.1.1 Order of Presentation 

The functions in this chapter are grouped by object type with the sections in alphabetical order by object 
name. However the object types Net, Port, and Portlnst are each kept in a section containing not only 
that supertype but all of its subtypes. Thus Net, NetBundle, NetBus, and NetScalar functions are all 
together in one section: Net Functions. Similarly, Port, PortBundle, PortBus, and PortScalar are in the 
section: Port Functions. Portlnst, PortlnstBundle, PortlnstBus, and PortlnstScalar are also all in one 
section: Portlnst Functions. 

Within each object type section, the order of the functions is strictly alphabetical. 

Note that two "pseudo-objects" are used in the DR-PI: 

1 . Functions which are addressed to the top-level environment instead of to a particular DR object 
are prefixed PI. 

Iterator is not a defined object in the Information Model, but it is the mechanism used to get the 
elements of Sets and Lists. All the Iterator operations use the object prefix Iter. 



5.1.2 Naming and Style Conventions 

Functions are named according to the Design Representation Working Group's understanding of the 
Specification Standards Working Group recommendations. Names are constructed from four parts: 

Example 1 Example 2 

1. prefix: cfidr cfidr 

target/subject: Cell NetBundle 

This is always the object type of the first parameter, except for the functions whose target/subject is PI 
which is a virtual target and not supplied as an argument 

verb: Create Insert 
return/object: View Net 

In the case of cfidrCeilCreateViewO, View is the type of the object that is returned. In the case of 
cfidrNetBundlelnsertNetO, the return type is void but the parameter owner is the NetBundle that, after 
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the function call, has the newly inserted Net (supplied as the net parameter) included in it. 

Compound names for any of the above items have their sub-parts capitalized: e.g., NetBundle. 

Entity instance references are capitalized: View. 

Entity type IDs as declared are bold: cfidrNetlistViewIdT. 

Relationship names are shown capitalized in italics: Describer 

Formal parameter names are italicized lower case: owner. 

Function name references are in bold followed by 0: cfidrNetUstViewGetPortsO 

Items whose PI names are abbreviated may be spelled out fully in textual descriptions: e.g, library for 
Lib, instance for Inst and iterator for Iter. 

5.1.3 Section Names and Meaning 

Each function description has up to nine sections: 

DECLARATION 
The ANSI C form of the function declaration. 

DESCRIPTION 
A text description of the operation performed by the function. 

[2] NOTE: When a DR-PI function can be implemented entirely using other DR-PI functions, it is called 
a "Level 2" function. This is shown by [2] after the function name in the section title and by a note 
labeled like this. 

RATIONALE 

A text description of additional, non-obvious, items that pertain to the operation of this function. 
RETURN VALUE 

A text description of return value(s) for this function including the value to be returned in case of error 
conditions. 

PARAMETERS 

For each formal parameter, a description of mat parameter including whether it is an input to or an 
output from the function. 

ERROR CODES 
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In the case of the error parameter, which is the last parameter to every function, each of the possible 
error codes is shown along with the conditions under which this error is to be returned. 

No precedence is implied by the order of error codes listed for any function. In the case where more than 
one error occurs, any of the error codes that apply may be returned. 

PRE-CONDITIONS 

Things that must be true before the function is executed. 

POST-CONDITIONS 

Additional things (beyond the main operation of the function) that are true after the function is executed. 

A compliant implementation of the DR-PI will ensure that all of the behavior documented in the 
description is followed, including the pre- and post-conditions. 

REFERENCES 

This is all other DR-PI functions relevant to the operation of this function: those with partial or similar 
functionality or those which could be called by or could call this function. 



5.2 Cell Functions 



5.2.1 cfidrCellCreateEncapsulatedView 

DECLARATION 

cfidrEncapsulatedViewIdT cfidrCellCreateEncapsulatedView( 

cfidrCellldT owner, 

cfidrStringT name, 

cfidrStringT viewType, 

cfidrStringT key, 

cfidrErrorT *error) 

DESCRIPTION 

This function creates an EncapsulatedView owned by the Cell specified via owner The 
EncapsulatedView has its Name attribute set to name, its ViewType attribute set to viewType, and its Key 
attribute set to fey. 

RETURN VALUE 

The return value is a cfidrEncapsulatedViewIdT referring to the Encapsulated View just created. If an 
error occurs, a Null OID is returned. 



PARAMETERS 
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owner (input) The OID of the Cell which owns the created EncapsulatedView. 
name (input) The string representing the name of the EncapsulatedView. 

viewType (input) The string representing a type classification of the EncapsulatedView. Example values 
are "VHDL behavior" or "Spice 14G Model". 

key (input) The string representing a "key" for the EncapsulatedView. This is an implementation- 
specific token for accessing the EncapsulatedView. It may be a file name, a design data manager name, 
a persistent object identifier, or other such item. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
owner is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
owner is not the OID of a Cell. 

CFIDR_£EAD_ONLY: 

The library that owns owner is not open for update. 
CFIDR_INVALID_NAME: 

the name parameter is not a valid string or is not a legal name. 
CFIDRJNVALID_VIEWTYPE: 

the viewType parameter is not a valid string or is the string reserved for the NetlistView: 
"CFIDRJNJETLISTVIEW." 

CFIDRJNVALID_KEY: 

the key parameter is not a valid string. 

CFIDRjOBJECTjULREADY JEXISTS: 
a View with the same name already exists. 

CFIDRJNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_3RROR: 
no error occurred. 

PRE-CONDITIONS 

The name argument must conform to the character set rules for name strings. 
POST-CONDITIONS 
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Insts (in NetlistViews) are never created with EncapsulatedViews as their Describes 

A created EncapsulatedView is not persistent across session boundaries until it is saved. 
REFERENCE 

cfidrNetiistViewCreatelnstO 

5.2.2 cfidrCeUCreateNetlistView 

DECLARATION 

cfidrNetlistViewIdT cfidiCeUCreateNetlistView( 
cfidiCellldT owner, 
cfidrStringT name, 
cfidrErrorT *error) 

DESCRIPTION 

This function creates a NetlistView owned by the Cell specified via owner. The NetlistView has its 
Name attribute set to name. 

RETURN VALUE 

The return value is a cfidrNetlistViewIdT referring to the NetlistView just created. If an error occurs, a 
Null OID is returned. 

PARAMETERS 

owner (input) The OID of the Cell which owns the created NetlistView. 
name (input) The string representing the name of the NetlistView. 

error (output) A pointer to the error returned if mis function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDRJJNUSABLE_OID: 
owner is not a usable OID. 

CFIDRJNVALID_OBJECTTYPE: 
owner is not the OID of a Cell. 

CFIDR_READ_ONLY: 

The library that owns owner is not open for update. 
CFIDRJNVALELNAME: 

the name parameter is not a valid string or is not a legal name. 
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CFIDR_OB JECT_ALREAD Y_EXISTS : 

a NetlistView with the same name already exists. 

CFIDRJNTERNAL_SYSTEMJERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

The name argument must conform to the character set rules for name strings. 
POST-CONDITIONS 

The ViewType attribute is automatically set to "CFIDRJ^TLISTVIEW." 

The cfidrlnstCheckDescriberO function can be used to determine whether there are discrepancies 
between an Inst and its Describer NetlistView. 

A created NetlistView is not persistent across session boundaries until it is saved. 
REFERENCE 

cfidiObjectDestroyO 

cfidrNetlistViewCreatelnstO 

cfidrlnstCheckDescriberO 



5.2.3 cfidrCellFmdViewByName 

DECLARATION 

cfidrViewIdTcfidrCellFindViewByName( 
cfidrCellldTcell, 
cfidrStringT name, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the View with the specified name mat is within the Views relationship defined for 
the Cell specified by cell. 

RATIONALE 

cfidrCellFindViewByNameO as currently defined will search all Views, Encapsulated and Netlist. This 
is reasonable since the current Information Model says names are unique across all Views. But if the 
Information model is changed so that separate namespaces are defined for Encapsulated and Netlist 
Views, then two different functions will be needed. 
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RETURN VALUE 

The return value is a cfidrViewIdT referring to the View just found. If an error occurs, a Null ODD is 
returned. 

PARAMETERS 

cell (input) The OID of the Cell from which the View is to be found, 
name (input) The name of the View. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
memory for this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
cell is not a usable OID. 

CTIDRJNVALID.OBJECTTYPE: 
cell is not the OID of a Cell. 

CFIDRJNVALID_NAME: 

the name parameter is not a valid string or is not a legal name. 

CFIDR_OBJECT_NOT _FOUND: 
no View with the specified name exists. 

CFIDRJMTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

POST-CONDITIONS 

If the View was not opened prior to this function call, it is opened automatically with access mode 
CFIDRJREAD. If the open fails, the error return for this function will be the error return of the open 
function. 

The function cfidrObjectGetObjectTypeO must be used on the returned object to determine whether it 
is a cfidrEncapsulatedViewIdT or a cfidrNetlistViewIdT 

REFERENCE 

cfidrObjectGetObjectTypeO 



5.2.4 cfidrCellGetOwner 
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DECLARATION 

cfidrLibldT cfidrCellGetOwner( 
cfidrCellldTcell, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the Lib at the end of the Owner relationship for the Cell specified by cell. The 
Owner relationship is defined when an object is created and cannot be modified. 

RETURN VALUE 

The return value is a cfidrLibldT referring to Lib at the end of the Owner relationship. If an error occurs, 
a Null OID is returned. 

PARAMETERS 

cell (input) The OID of the Cell whose Owner relationship is to be followed. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
cell is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
cell is not the OID of a Cell. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 



5.2.5 cfidrCeUGetViews 

cfidrViewsIdT cfidrCellGetViews( 

cfidrCellldTcell, 

cfidrErrorT *error) 

DESCRIPTION 

This function initiates a traversal of all of the Views at the end of the Views relationship defined for the 
Cell specified by cell. 

RETURN VALUE 
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The return value is a cfidrViewsIdT referring to an Iterator ID that iterates over Views. A valid Iterator 
ID is always returned, even when an error occurs. In the case of an error, calling the cfidrlterNextView 
0 function returns a Null ODD. 

PARAMETERS 

cell (input) The OID of a Cell for which the Views relationship is to be traversed. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR w UNUSABLE_OID: 
cell is not a usable OID. 

CFIDRJNVALID_OBJECTTYPE: 
cell is not the OID of a Cell. 

CFIDIUNTERNAL_SYSTEMJERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

POST-CONDITIONS 

The cfid r Iter Next View 0 function returns the next View OID in the Views relationship. If the View was 
not opened prior to the call to cfidrlterNextViewO, it is opened automatically (i.e., all views are 
iterated, whether they are opened or not). The AccessMode for the open will be CFIDR^READ. If the 
open fails, the error return for this function will be the error return of the open. 

If no objects are currently present in the Views relationship, an error is not returned but the first call to 
cfidrlterNextViewO returns a Null OID. 

REFERENCE 
cfidrlterNextViewO 



5.3 Instance Functions 



5.3.1 cfidrlnstCheckDescriber [2] 

DECLARATION 

cfidrBooleanT cfidrInstCheckDescriber( 
cfidrlnstldT inst, 
cfidrEnorT *error) 
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DESCRIPTION 

This function checks for discrepancies between the Inst specified via inst and its Describer View. In 
addition to checking the Inst against the View, this function checks all of the Portlnsts owned by the Inst 
against their Describer Ports. 

Checking is performed on all Portlnsts owned either directly or indirectly by inst (as returned by 
cfidrlnstGetPortlnsts with mode ITER^ALL). 

[2] NOTE: This function can be written entirely using other DR-PI functions. The principal other 
functions required are: cfldrlnstGetDescriberO, cfldrlnstGetPortlnstsO, cfidrPortlnstGetDescriber 
0, and cfidrNetlistViewGetPortsO 

RETURN VALUE 

If no discrepancies are found between the Inst and the Describer View, CFIDR^FALSE is returned. 
Otherwise, CFIDRJTRUE is returned and the error output argument will denote the discrepancy. 

PARAMETERS 

inst (input) The OID of the Inst to check against its Describer View. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
inst is not a usable OID. 

CFmR^INVALro^OBJECTTYPE: 
inst is not the OID of an Inst. 

CFIDR^DESCRIBER.VIEW^NOTJOUND: 
could not find or access the Describer View for inst. 

CFIDR^DESCRIBERJORTJ^OTJOUND: 

at least one Portlnst on the inst does not have a corresponding Port on the inst Describer View. 
CFIDR^fEWJDESCRIBER^PORTJOUND: 

there is at least one additional Port on the inst Describer View that does not correspond to any Portlnst 
on inst. 

CFIDR^PORT ^MEMBERS JDIFFER: 

the Members of at least one PortlnstBundle differ from the Members of the corresponding PortBundle. 
This code is also used if the Describer Port is a Scalar but the Portlnst is a Bundle or the Describer is a 
Bundle, but the Portlnst is a Scalar. This error is also returned if the owner of the describer of a Portlnst 
is not the same object as the describer of the owner of that Portlnst. 

CFIDRJNTERNAL_SYSTEMJERROR: 
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some other error occurred. 

CFIDRJ^OJERROR: 
no error occurred. 

POST-CONDITIONS 

If the Describer View is not opened yet, then this function will attempt to open it. The AccessMode for 
the open will be CFIDRJtEAD. If the open fails, the error return for this function will be the error 
return of the open 

REFERENCE 

cfidrlnstGetDescriberO 

cfidrlnstGetPortlnstsO 

cfidrPortlnstGetDescriberO 

cfidrNetlistViewGetPortsO 

cfidrPIOpenViewQ 



5.3.2 cfidrlnstFindPortlnstByDescriberName 

DECLARATION 

cfidrPortlnstldT cfidrInstFindPortInstByDescriberName( 
cfidrlnstldT inst, 
cfidrStringT describerName, 
cfidrErroiT * error) 

DESCRIPTION 

This function returns the Portlnst (either PortlnstBundle or PortlnstScalar) with the specified 
describerName that is within the Portlnsts relationship defined for the Inst specified by inst. All 
Portlnsts are scoped to their Owner (either Inst or PortlnstBundle), therefore Portlnsts contained in 
PortlnstBundles are not searched by this function. 

RETURN VALUE 

The return value is a cfidrPortlnstldT referring to the Portlnst just found. If an error occurs, a Null OID 
is returned. 

PARAMETERS 
inst (input) The OID of the Inst from which the Portlnst is to be found. 
describerName (input) The DescriberName of the Portlnst 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating memory for 
this parameter. 

ERROR CODES 



http://www.si2.org/si2^ubH^ 



6/23/2004 



Page 12 of 89 



CFIDR_UNUSABLE_OID: 
inst is not a usable OID. 

CFIDIUNVALID.OBJECTTYPE: 
inst is not die OID of an Inst. 

CFIDRJOSfVALID_NAME: 

the describerName parameter is not a valid string or is not a legal name. 

CFIDR_OBJECT_NOT_FOUND: 

no Portlnst with the specified describerName exists. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO _ERROR: 
no error occurred. 



5.3.3 cfidrlnstGetDescriber 

DECLARATION 

cfidrNetlistViewIdTcfidrInstGetDescriber( 

cfidrlnstldTinst, 

cfidrErrorT *error) 

DESCRIPTION 

This function returns the View at the end of the Describer relationship for the Inst specified by inst. 
RETURN VALUE 

The return value is of type cfidrNetlistViewIdT and is the NetlistView at the end of the Describer 
relationship. If an error occurs, a Null OID is returned. 

PARAMETERS 

inst (input) The OID of the Inst whose Describer relationship is to be followed. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
inst is not a usable OID. 

CFIDR^INVALIDjOBJECTTYPE: 
inst is not the OID of an Inst 
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CFIDRJ>ESOUBER_VIEW_NOT -FOUND: 
the Describer View for inst does not exist 

CHDR_VIEW_OPEN_FAILED: 

the Describer Netlist View could not be opened for some reason, such as lack of access rights. 

CFIDR_INTERNAL_SYSTEM_JERROR: 
some other error occurred. 

CFIDR^NOJERROR: 
no error occurred. 

POST-CONDITIONS 

If the Describer View is not open, this function will attempt to open it. The AccessMode for the open 
will be CFIDR_READ. 

i 

REFERENCE 

cfidrlnstCheckDescriberO 

cfidrPortlnstGetDescriberO 

cfidrPIOpenViewO. 



5.3.4 cfidrlnstGetOwner 

DECLARATION 

cfidrNetlistViewIdT cfidrInstGetOwner< 
cfidrlnstldT inst, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the View at the end of the Owner relationship for the Inst specified by inst. Note: 
The Owner relationship is defined when an object is created and cannot be modified. 

RETURN VALUE 

The return value is a cfidrNetlistViewIdT referring to the NetlistView at the end of the Owner 
relationship. If an error occurs, a Null OID is returned. 

PARAMETERS 

inst (input) The OID of the Instance whose Owner relationship is to be followed. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 
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CFIDRJJNUSABLEJDID: 
inst is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
inst is not the OID of an Inst 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 



53.5 cfidrlnstGetPortlnsts 

DECLARATION 

cfidrPortlnstsId cfidrInstGetPortInsts( 
cfidrlnstldT inst, 
cfidrlterModeT mode, 
cfidrErrorT *error) 

DESCRIPTION 

This function initiates a traversal of all of the Portlnsts (PortlnstB undies, PortlnstBusses, or 
PortlnstScalars) at the end of the Portlnsts relationship defined for the Inst specified by inst. 

RETURN VALUE 

The return value is a cfidrPortlnstsIdT which is the ID of an Iterator that returns Portlnsts. A valid 
Iterator ID is always returned, even when an error occurs. In the case of an error, calling the 
cfidrlterNextPortlnstO function returns a Null OID. 

PARAMETERS 

inst (input) The OID of an Inst for which the Portlnsts relationship is to be traversed. 

mode (input) The mode that determines which Portlnsts are returned. The current valid values are 
CFIDR_JTER_SCALARS, CFIDR_JTER_PUNDLES, CFIDR_ITER_TOP, and CFIDR_ITER_ALL. 
See the Pre-Conditions below for more detail on how these modes behave. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
inst is not a usable OID. 

CTIDR_JNVALID_OBJECTTYPE: 
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inst is not the OID of an Inst 

CFIDRjnMVALIDJTERMODE: 
mode is not a valid IterMode. 

CFIDR_JNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NOJERROR: 
no error occurred. 

PRE-CONDITIONS 

The Portlnsts returned depends on the mode argument specified. 
/MOGfe=CFJDRJTERJTOP 

Returns all those Portlnsts (PortlnstBundles, PortlnstBusses, or PortlnstScalars) which are owned 
directly by the Inst (i.e., not owned by a PortlnstBundle). 

We^FIDRJTERJSCALARS 

Returns all the PortlnstScalars owned directly or indirectly by the Inst. No PortlnstBundles are output 
with this mode. 

»M></e=CFD>R_ITERJBUNDLES 

Returns all the PortlnstBundles owned directly or indirectly by the Inst. No PortlnstScalars are output 
with this mode. 

mo<fe=CFIDR_ITER_ALL 

Returns all the Portlnsts (PortlnstBundles, PortlnstBusses or PortlnstScalars) owned directly or 
indirectly by the Inst This is the union of all the Portlnsts returned by the CFIDR_JTER_SCALARS 
and CFIDRJTER JBUNDLES modes. 

Depth-first recursion is used for all modes except CFIDR_ITER_TOP. 
POST-CONDITIONS 

The cfidrlterNextPortlnstO function returns the next Portlnst OID in the Portlnsts relationship. 

If no objects are currently present in the Portlnsts relationship, an error is not returned, but the first call 
to cfidrlterNextPortlnstO returns a Null OID. 

The Portlnst name scoping rules (inherited from the Port name scoping rules) state that Portlnst names 
are only unique within their immediate owner (either an Inst or a PortlnstBundle). Thus, two Portlnsts 
with the same name may exist and be completely different objects. Thus, Portlnsts returned via any 
mode except CFIDRJ(TER_TOP may have the same name but in fact be different objects. The 
cfidrObjectlsSameO function can be used to determine if any two of these Portlnsts are the same. 

REFERENCE 
CfidrlterNextPortlnstO 
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cfidrObjectlsSameO 

5.4 Iterator Functions 
5.4.1 cfidrlterNextCell 

DECLARATION 

cfidrCellldT cfidrIterNextCell( 
cfidrCellsIdTiter, 
cfidrErrorT * error) 

DESCRIPTION 

This function returns another Cell object from the Iterator ID specified via iter. 
RETURN VALUE 

The return value is a cfidrCellldT referencing the Cell just iterated. If an error occurs or there are no 
more objects to iterate, a Null OID is returned. If there are no more objects to iterate, this is not an error. 

PARAMETERS 

iter (input) The Iterator ID representing an Iterator of Cell objects. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_INVALID_ITER: 

iter is not the ID of a valid Iterator. 

CFIDR_JNVALID_JTER_TYPE: 
iter is not the ID of an Iterator of Cells. 

CFIDR_JNTERNALjSYSTEM_ERROR: 
some other error occurred. 

CFIDR w NQ_JiRROR: 
no error occurred. 

PRE-CONDITIONS 

The iter argument must have been returned via a previous call to cfidrLibGetCeUsO 
REFERENCE 
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5.4.2 cfidrlterNextlnst 

DECLARATION 

cfidrlnstldT cfidrIterNextInst( 
cfidrlnstsIdT iter, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns another Inst object from the Iterator ID specified via iter. 
RETURN VALUE 

The return value is a cfidrlnstldT referencing the Inst just iterated. If an error occurs or there are no 
more objects to iterate, a Null OID is returned. If there are no more objects to iterate, this is not an error. 

PARAMETERS 

iter (input) The Iterator ID representing an Iterator of Inst objects. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_INVALID_ITER: 

iter is not the ID of a valid Iterator. 

CFIDRJNVALID JTERJTYPE: 
iter is not the ID of an Iterator of Insts. 

CFIDR_JNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDRJNO_ERROR: 
. no error occurred. 

PRE-CONDITIONS 

The iter argument must have been returned via a previous call to cfidrNetlistViewGetlnstsO 
REFERENCE 

cfidrNetlistViewGetlnstsO 
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5.4.3 cfidrlterNextLib 

DECLARATION . 

cfidrLibldT cfidrIterNextLib( 
cfidrLibsWT iter, 
cfidrErroiT *error) 

DESCRIPTION 

This function returns another Lib (library) object from the Iterator ID specified via iter. 

RETURN VALUE 
The return value is a cfidrLibldT referencing the Lib object just iterated. 

If an error occurs or there are no more Libs to iterate, a Null OID is returned. If there are no more Libs 
to iterate, this is not an error. 

PARAMETERS 

iter (input) The Iterator ID representing an Iterator of Lib objects. 

error (output) A pointer to the error returned if this function fatts. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_INVALID_ITER: 

iter is not the ID of a valid Iterator. 

CFIDR_INVALID_ITER_TYPE: 

iter is not the ID of an Iterator of Lib objects. 

CFIDR_INTERNAL_SYSTEMJERROR: 
some other error occurred. 

CFIDRJNOJERROR: 
no error occurred. 

PRE-CONDITIONS 

The iter argument must have been returned via a previous call to cfidrPIGetLibsO- 

POST-CONDITIONS 

If the Lib is not already open, this function will attempt to open it. The AccessMode for the open will be 
CFIDRJREAD. If the open fails, the error return for mis function will be the error return of the open. 
The iteration sequence can continue after a failed Lib open. 
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REFERENCE 
cfidrPIGetLibsO 



5.4.4 cfidrlterNextNet 

DECLARATION 

cfidrNetldT cfidrIterNextNet( 
cfidrNetsIdTiter, 
cfidrEmorT *error) 

DESCRIPTION 

This function returns another Net object (NetBundle, NetBus, or NetScalar) from the Iterator ID 
specified via iter. 

RETURN VALUE 

The return value is a cfidrNetldT referencing the Net just iterated. If an error occurs or there are no more 
objects to iterate, a Null OID is returned. If there are no more objects to iterate, this is not an error. 

PARAMETERS 

iter (input) The Iterator ID representing an Iterator of Net objects. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDRJNVALID JTER: 

iter is not the ID of a valid Iterator. 

CFIDR_INVALID_ITER_TYPE: 
iter is not the ID of an Iterator of Nets. 

CFIDR_JNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NOJERROR: 
no error occurred. 

PRE-CONDITIONS 

The iter argument must have been returned via a previous call to cfidrNetBundleGetNetsO or 
cfidrNetlistViewGetNetsO. 

POST-CONDITIONS 
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Nets in a NetBundle are ordered with Positions from 0 to one less than the number of nets in the bundle. 
When nets are being returned from a NetBundle they are returned in order of their Position. A net can be 
inserted in a Bundle at a particular position using by the cGdrNetBundlelnsertNetO function which 
also causes all nets to the "right" of the newly inserted one to increase their Position by one. Net 
ordering is also affected by use of the cfidrNetBundleRemoveNetO function which causes all nets to 
the "right" of the removed net to decrease their position by one. 

Nets being returned from the View are not returned in any guaranteed order. 
REFERENCE 

cfidrNetlistViewGetNetsO 

cfidrNetBundlelnsertNetO 

CfidrNetBundleRemoveNetO 

cfidrNetBundleGetNetsO 

cfidrNetGetNetBundlesO 

cfidrPortBundleGetNetBundlesO 

cfidrPortlnstBundleGetNetBundlesO 



5.4.5 cfidrlterNextNetBundle 

DECLARATION 

cfidrNetBundleldT cfidrIterNextNetBundle{ 
cfidrNetBundlesIdT iter, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns another NetBundle object from the Iterator ID specified via iter. 
RETURN VALUE 

The return value is a cfidrNetBundleldT referencing the NetBundle just iterated. If an error occurs or 
there are no more objects to iterate, a Null OED is returned. If there are no more objects to iterate, this is 
not an error. 

PARAMETERS 

iter (input) The Iterator ID representing an Iterator of NetBundle objects. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDRJNVALIDJTER: 

iter is not the ID of a valid Iterator. 
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CFmRJNVALIDJTERJTYPE: 

iter is not the ID of an Iterator of NetBundles. 

CFIDRJNTERNAL_SYSTEMJERROR: 
some other error occurred. 

CFIDR_NCLERROR: 
no error occurred. 

PRE-CONDITIONS 

The iter argument must have been returned via a previous call to cfidrNetGetNetBundlesO, 
cfidrPortBundleGetNetBundlesO.cfidrPortlnstBundleGetNeiBundlesO 

REFERENCE 

cfidrNetGetNetBundlesO 

cfidrPortBundleGetNetBundlesO 

cfidrPortlnstBundleGetNetBundlesO 



5.4.6 cfidrlterNextPort 

DECLARATION 

cfidrPortldT cfidrIterNextPort( 
cidrPortsIdT iter, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns another Port object (PortBundle, PortBus, or PortScalar) from the Iterator ID 
specified via iter. 

RETURN VALUE 

The return value is a cfidrPortldT referencing the Port just iterated. If an error occurs or there are no 
more objects to iterate, a Null OID is returned. If there are no more objects to iterate, this is not an error. 

PARAMETERS 

iter (input) The Iterator ID representing an Iterator of Port objects. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_JNVALID_JTER: 

iter is not the ID of a valid Iterator. 
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CFIDR JNVALIDJTER^TYPE: 
iter is not the ID of an Iterator of Ports. 

CFIDR L JNTERNALJ5YSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

The iter argument must have been returned via a previous call to CfidrNetlistViewGetPortsO, 
cfidrPortBundleGetPortsO, or cfidrNetGetPortsQ 

POST-CONDITIONS 

Ports are returned in the order of their Position either in the View or in the PortBundle. Position is 
specified at creation time or using cfidrPortSetOwnerViewO or cfidrPortSetOwnerPortBundle(). 

REFERENCE 

cfidrNetlistViewGetPortsO 

cfidrPortBundleGetPortsO 

cfidrPortSetOwnerPortBundleO 

cfidrPortSetOwnerViewO 

cfidrNetGetPortsO 



5.4.7 cfidrlterNextPortlnst 

DECLARATION 

cfidrPortlnstldT cfidrIterNextPortInst( 
cfidrPortlnstsIdT iter, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns another Portlnst object (PortlnstBundle, PortlnstBus, or PortlnstScalar) from the 
Iterator ID specified via iter. 

RETURN VALUE 

The return value is a cfidrPortlnstldT referencing the Portlnst just iterated. If an error occurs or there are 
no more objects to iterate, a Null OID is returned. If there are no more objects to iterate, this is not an 
error. 

PARAMETERS 

iter (input) The Iterator ID representing an Iterator of Portlnst objects. 
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error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDIUNVALIDJTER: 

iter is not the ID of a valid Iterator. 

CFIDR_INVALID_ITERJTYPE: 

iter is not the ID of an Iterator of Portlnsts. 

CFIDRJNTERNAL_SYSTEMJERROR: 
some other error occurred. 

CFIDR.JNOLERROR: 
no error occurred. 

PRE-CONDITIONS 

The iter argument must have been returned via a previous call to cfidrlnstGetPortlnstsO, 
cfiPortlnstBundleGetPortlnstsO, or cfidrNetGetPortlnstsO- 

REFERENCE 

cfidrlnstGetPortlnstsO 

cfidrPortlnstBundleGetPortlnstsO 

cfidrNetGetPortlnstsO 



5.4.8 cfidrlterNextProp 

DECLARATION 

cfidrPropIdT cfidrIterNextProp( 
cfidrPropsIdT iter, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns another Property object from the Iterator ID specified via iter. 
RETURN VALUE 

The return value is a cfidrPropIdT referencing the Property just iterated. If an error occurs or there are 
no more objects to iterate, a Null OID is returned. If there are no more objects to iterate, this is not an 
error. 

PARAMETERS 

iter (input) The Iterator ID representing an Iterator of Property objects. 
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error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_INVALID JTER: 

iter is not the ID of a valid Iterator. 

CFIDR_INVALID_ITER_TYPE: 
iter is not the ID of an Iterator of Props. 

CFIDR_INTERNAL_SYSTEM J5RROR: 
some other error occurred. 

CFIDR_>fO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

The iter argument must have been returned via a previous call to cfidrObjectGetPropsO- 
REFERENCE 

cfidrObjectGetPropsO 

5.4.9 cfidrlterNextView 

DECLARATION 

cfidrViewIdT cfidrIterNextView( 
cfidrViewsIdT iter, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns another View object from the Iterator ID specified via iter. 
RETURN VALUE 

The return value is a cfidrViewIdT referencing the View just iterated. If an error occurs or there are no 
more objects to iterate, a Null OID is returned. If there are no more objects to iterate, this is not an error. 

PARAMETERS 

iter (input) The Iterator ID representing an Iterator of View objects. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 
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ERROR CODES 

CFIDRJNVALIDJTER: 

iter is not the ID of a valid Iterator. 

CFIDRJNVALIDJTERjrYPE: 

iter is not the ID of an Iterator of Views. 

CFIDR_JNTERNAL_SYSTEM _£RROR: 
some other error occurred. 

CFIDRJ40JBRROR: 
no error occurred. 

PRE-CONDITIONS 

The iter argument must have been returned via a previous call to cfidrCellGetViewsO- 
POST-CONDITIONS 

If the View was not open prior to calling this function, it is opened automatically. The AccessMode for 
the open will be CFIDRJtEAD. If the open fails, the error return for this function will be the error 
return of the open. The iteration sequence can continue after a failed open. 

The function CfidrObjectGetObjectTypeO must be used to determine whether each View is an 
EncapsulatedView or a NetlistView. 

REFERENCE 

cfidrCellGetViewsO 
CfidrObjectGetObjectTypeO 



5.4.10 cfidrlterQuit 

DECLARATION 

cfidrVoidT cfidrIterQuit( 
cfidrlterldT iter, 
cfidrErrorT *error) 

DESCRIPTION 

This function exits from a previously initialized Iterator specified via iter. This function is called once 
for each Iterator ID created. It is the application's responsibility for calling this function. 

PARAMETERS 

iter (input) The Iterator ID referring to the Iterator to be terminated. 
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error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR^INVALID JTER: 

iter is not the ID of a valid Iterator. 

CFIDRJNTERNAL^YSTEMJRROR: 
some other error occurred. 

CFIDRJJO^ERROR: 
no error occurred. 

POST-CONDITIONS 

Once this function is called, trying to use the Iterator ID with any other function should result in an 
error. 

5.4.11 cfidrlterReset 

DECLARATION 

cfidrVoidT cfidrIterReset( 
cfidrlterldT iter, 
cfidrErrorT *error) 

DESCRIPTION 

This function resets the Iterator specified via iter such that it starts over from its beginning. 
RETURN VALUE 

None. If there is an error, calling the appropriate cfidrlterNext.. function returns a Null OID. 

PARAMETERS 
iter (input) The Iterator ID referring to the generator to reset. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDRJNVALID _JTER: 

iter is not the OID of a valid Iterator. 

CFIDR_JNTERNAL_SYSTEMJERROR: 
some other error occurred. 
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CFIDIUJO^ERROR: 
no error occurred. 

POST-CONDITIONS 

The Iterator is reset such that calling the appropriate cfidrlterNext.. function will iterate the first object. 

NOTE: The order of the objects iterated after resetting the Iterator is guaranteed to be same as the 
previous iteration if and only if the relationship itself is ordered (is a List). 



5.5 Lib (library) Functions 



5.5.1 cfidrLibCreateCell 

DECLARATION 

cfidrCellldT cfidrLibCreateCell( 
cfidrLibldT owner, 
cfidrStringT name, 
cfidrErrorT *error) 

DESCRIPTION 

Tins function creates a Cell object with its Name attribute set to name and owned by the Lib specified 
via owner. 

RETURN VALUE 

The return value is a cfidiCellldT which refers to the Cell object just created. If an error occurs, a Null 
OID is returned. 

PARAMETERS 

owner (input) The OID of the Lib object which owns the Cell. 
name (input) The string representing the name of the Cell to create. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
owner is not a usable OID. 

CFroRjnWALID.OBJECTTYPE: 
owner is not the OID of a Lib. 
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CFIDR_READ_ONLY: 

the library has not been opened for update. 

CFIDR_INVALID_>IAME: 

the name parameter is not a valid string or is not a legal name. 

CFIDR_OBJECT _ALREADY_EXISTS: 
a Cell with the same name already exists. 

CFIDRJNTERNAL_SYSTEMJBRROR: 
some other error occurred. 

CFIDRJvJOJERROR: 
no error occurred. 

PRE-CONDITIONS 

The Lib specified by owner must previously have been created or opened for update. 
The name argument must conform to the character set rules for name strings. 

POST-CONDITIONS 

A created Cell object is not persistent across session boundaries until the Lib owning the Cell is saved. 



5.5.2 cfidrLibFindCellByName 

DECLARATION 

cfidrCellldT cfidrLibFindCellByName( 
cfidrLibldTlib, 
cfidrStringT name, 
cfidrErroiT *enor) 

DESCRIPTION 

This function returns the Cell with the specified name that is within the Cells relationship defined for the 
Lib specified by lib. 

RETURN VALUE 

The return value is a cfidrCellldT referring to the Cell just found. If an error occurs, a Null OID is 
returned. 

PARAMETERS 

lib (input) The OID of the Lib fiom which the Cell is to be found, 
name (input) The name of the Cell. 
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error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
memory for this parameter. 

ERROR CODES 

CFIDRJUNUSABLE_OID: 
lib is not a usable OID. 

CFIDR^INVALID_OBJECTTYPE: 
lib is not the OID of a Lib. 

CFIDR_INVALID_NAME: 

the name parameter is not a valid string or is not a legal name. 

CFIDR w OBJECT - NOT_FOUND: 
no Cell with the specified name exists. 

CFIDRJNTERNAL_SYSTEM JERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 



5.5.3 cfidrLibGetCeUs 

DECLARATION 

cfidiCellsIdT cfidrLibGetCells( 
cfidrLibldT lib, 
cfidrErrorT *error) 

DESCRIPTION 

This function initiates a traversal of all of the Cells at the end of the Cells relationship defined for the 
Lib specified by lib. 

RETURN VALUE 

The return value is a cfidrCellsIdT referring to an Iterator ID that iterates over Cells. A valid Iterator ID 
is always returned, even when an error occurs. In the case of an error, calling the cfidrlterNextCellfJ 
function returns a Null OID. 

PARAMETERS 

lib (input) The OID of the Lib for which the Cells relationship is to be traversed. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 
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ERROR CODES 

CFIDR_UNUSABLE_OID: 
lib is not a usable OK). 

CFIDRJNVALID_OBJECTTYPE: 
lib is not the OID of a Lib. 

CFIDFUNTERNAL_SYSTEM JSRROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

POST-CONDITIONS 

The cfidrlterNextCellO function returns the next Cell OID in the Cells relationship. 

If no objects are currently present in the Cells relationship, an error is not returned but the first call to 
cfidrlterNextCellO returns a Null OID. 

REFERENCE 
cfidrlterNextCellO 



5.5.4 cfidrLibPurge 

DECLARATION 

cfidrVoidT cfidrLibPurge( 
cfidrLibldT lib, 
cfidrErrorT *error) 

DESCRIPTION 

This function purges the Lib (library) specified via lib. The effect of purging a Lib is to also purge the 
entire Object hierarchy owned by the purged Lib. 

PARAMETERS 

lib (input) The OID of the Lib to purge. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
lib is not a usable OID. 
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CFIDRJNVALIDjOBJECTTYPE: 
lib is not the OID of a Lib 

CFIDRJNTERNALJSYSTEMJERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

A Lib can be purged regardless of the access mode of any object. 
POST-CONDITIONS 

Any OIDs referring to purged Libs are made unusable. They may be reused to refer to other Libs at 
some pou* so the application cannot assume that if the purged Lib is again made available (via open 
create, etc.), mat it will have the same OID. 

Policy: The purge operation removes any changes made to an object since the last save or open. The 
object then becomes unavailable and its OID becomes unusable. Opening the Lib again assigns the Lib 
an OID and makes it available for updating. 

An example implementation that would provide this behavior would make an in-memory copy of the 
Lib and its contained objects. All edits would be made only to the in-memory copy of the objects The 
obj^mcha^ed 1$ t0 rem ° Ve in " mem0iy of ** objects ' Ieavin 8 ** original disk copy of the 

Policy- Similar to open, purge also recursively walks the ownership hierarchy rooted by the specified 
Lib and purges all Objects in this hierarchy. Unlike open, purge continues walking the ownership 
hierarchy when it encounters an Object which can be purged individually. Thus, purge behaves 
similarly to save in this respect F B 

Rationale: Consider the information model and take into account the policy that only Libraries and 
Views can be purged. Purging a Lib not only purges the Lib and Cells, it also purges all the Views as 

Rationale: When opening a Lib, opening all the Views automatically is probably undesirable in most 
situations. However, when purging a Lib, it does not make sense to only purge the Lib and Cells and not 
the Views. 

REFERENCE 

cfidrLibSaveO 
cfidrViewPurgeO 

5.5.5 cfidrLibSave 

DECLARATION 
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cfidrVoidT cfidrLibSave( 
cfidrLibldT lib, 
cfidrErrorT *error) 

DESCRIPTION 

This function saves the Lib (Hbraiy) specified via lib. Saving a Lib makes aU updates to objects in the 
Lib's hierarchy persistent If the Lib has been opened for CFIDRJtEAD, changes to the Views 
contained in the Lib that are open for CFIDR_UPDATE will be made persistent. All Views owned by 
all Cells owned by lib will be also saved by this function. 

RATIONALE 

This function is a "brute force" save-eveiything-below-me function. Incremental saves to particular 
Views should be done using cfidrViewSaveO which will only save whatever portions of the Lib are 
necessary to ensure referential integrity. 

PARAMETERS 

lib (input) The OID of the Lib to save. The Objects owned by lib are also saved. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
lib is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
lib is not the OID of a Lib. 

CFIDR_INTERNAL_SYSTEMLERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

Any View that is owned by a Cell owned by lib but which is NOT to be saved must first be purged with 
cfidrViewPurgeO or destroyed with cfidrObjectDestroyO before calling cfidrLibSaveO- 

POST-CONDITIONS 

All Views owned by all Cells owned by lib are now persistant and can later be retreived using 
cfidrViewOpenO or by cfidrLibOpenO followed by traversal of the Cells of the Lib and the Views of 
the Cells. 

If Views owned by Cells owned by lib are created or destroyed after the execution of this function then 
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explicit calls to cfidrViewSave 0 can be used to update the Lib and ensure that it has Cells owning those 

^b^ctDet^yO. ^ kn0Wn ^ aVail8ble ° Pening am>SS SeSSi ° n }KmMtt mtil deStr ° yed * 

Saving does not invalidate OIDs referring to the saved Lib. 

REFERENCE 

cfidrObjectDestroyO 
cfidrPIQuitO 
cfidrViewPurgeO 
cfidrViewSaveQ 



5.6 Named Object Functions 



5.6.1 cfidrNamedObjectGetName 

DECLARATION 

cfidrStringT cfidrNamedObjectGetName( 
cfidrNamedObjectldTnamedObject, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the Name attribute of the NamedObject specified by namedObject. 
RETURN VALUE 

Thereturn value is a cfidrStringT representing the Name of the object On error the empty string "« is 
PARAMETERS 

namedObject (input) The OID of the NamedObject whose Name attribute is desired. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDRJJNUSABLEJDID: 
namedObject is not a usable OID. 

CFIDRjNVALID_OBJECTTYPE: 



http://www.si2.org/si2jublicatioiis/hu^ 



6/23/2004 



Page 34 of 89 



namedObject is not the OID of a NamedObject 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NOJERROR: 
no error occurred. 

PRE-CONDITIONS 

Note that Portlnsts only have a DescriberName attribute which must be accessed via the 

cfidrPortlnstGetDescriberNameO function. There are other ViewSelection objects which do not have 
a Name attribute. 

POSTCONDITIONS 

The string returned is guaranteed to conform to the rules for name strings. 

The memory for the string is managed by the DR-PI. The string's value remains valid until the next 
fcSueT y ° n Whi ° h 3 cfidrStrin 8 T retum value or ^1 ^ function cfidrprguitQ 

REFERENCE 

cfidrNamedObjectSetNameO 
cfidrPIQuitO 

CfidrPortlnstGetDescriberNameO 

5.6.2 cfidrNamedObjectSetName 

DECLARATION 

cfidrVoidT cfidrNamedObjectSetName( 
cfidrNamedObjectldT namedObject, 
cfidrStringT name, 
cfidrErroiT *error) 

DESCRIPTION 

This function sets the Name attribute of the NamedObject specified via namedObject. 
PARAMETERS 

namedObject (input) The OID of the NamedObject for which the Name attribute is set. 

name (input) The string to set the Name attribute to. The caller is responsible for managing the memory 
of this string. 

NOTE: DR-PI functions which return cfidrStringT values guarantee those strings to not be updated 
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until the next call to a PI function that returns another cfldrStringT. These strings can be used as the 
name argument because the cfidrNamedObjectSetNameO function will not affect these strings 
returned from other PI functions. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
namedObject is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
namedObject is not the OID of a NamedObject 

NOTE: At the moment all objects (except Portlnsts, ViewNameSelectors, ViewTypeSelectors, and 
Library Selectors) are namedObjects. 

CFIDRJLLEGALjOPERATION: 

namedObject is not allowed to have the name changed at this time. 

t 

CFIDR_READ_ONLY: 

the containing object (Lib or View) has not been opened for update. 
CFIDR_JNV ALID_N AME : 

name parameter is not a valid string or is not a legal name. 
CFIDR_NAME_IN_USE: 

another NamedObject in the same name scope already is using the name name. 

CFIDRJNTERNAL_SYSTEMLERROR: 
some other error occurred. 

CFIDR_>fO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

The name argument must conform to the character set rules that apply to all name strings. Any violation 
of the rules results in an error and the Name attribute not being set. 

Note that all subtypes of cfidrNamedObject have a Name attributes. However, some of these names 
cannot be updated or have limitations as to when name changes are allowed. The behavior of each object 
type is: 

Lib 

Policy: The Lib's Name attribute cannot be set. 

Rationale: Issues surround update of Insts referencing Describer Views. 
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Cell 

Policy: The Cell's Name attribute cannot be set. 

Rationale: Issues surround update of Insts referencing Describer Views. 

View 

Policy: The View's Name attribute cannot be set To change a View's Name, it must be deleted and re- 
created. 

Rationale: Issues surround update of Insts referencing Describer Views. 
Port 

Policy: A Porf s Name attribute (either a PortBundle Name or PortScalar Name) cannot be set. To change 

a Port's Name, the Port must be deleted and re-created. 

Rationale: Issues surround update of Portlnsts referencing Describer Ports. 

Net 

Policy: A Net Name (either a NetBundle, NetBus, or NetScalar Name) can only be set when the Net is 
completely un-connected. This means that the Nets contained by the NetBundle must also be completely 
un-connected. 

Rationale: Allowing the Net Name to be set when connected to Ports or Portlnsts may affect the validity 
of those connections on some systems. 

Policy: A Net's Name must be unique with respect to all other Nets owned by the same NetlistView. 
Rationale: This follows from the name uniqueness and scoping rules for NetScalars. 

Inst 

Policy: Hie Name attribute must be unique with respect to existing Insts owned by the NetlistView. 
Property 

Policy: The Name attribute must be unique with respect to existing Property objects owned by the 
Property's owner, 

SelectorSets 

The Name attribute must be unique with respect to existing SelectorSet objects. 
ViewNameSelectors, ViewTypeSelectors, and LibrarySelectors are not NamedOjects.. 
POST-CONDITIONS 

The updated object must be saved in order to be persistent. Purging the object before saving it will result 
in the loss of the changes. 

REFERENCE 



http://www.si2.org/si2jubh^ 



6/23/2004 



cfidrNamedObjectGetNameO 



Page 37 of 89 



5.7 Net Functions 



5.7.1 cfidrNetAttachPort 

DECLARATION 

cfidrVoidT cfidrNetAttachPort( 
cfidrNetldT net, 
cfidrPortldTport, 
cfidrAttachModeT mode, 
cfidrErrorT *error) 

DESCRIPTION 

This function connects the specified net and port. If there are no errors, it adds port to the Ports attribute 
of net and sets the NetScalar attribute of port to net. 

RATIONALE 

This function only directly attaches Scalars. It also "power" connects members of Bundles while 
recursively traversing the bundle hierarchy. NetBundle to PortBundle connection is an indirect effect of 
connections of members of those bundles ultimately due to some underlying Scalar connection. 

RETURN VALUE 

No function return value but error indicates status or success of connection. 

PARAMETERS 
net (input) The OID of a Net (Scalar, Bundle, or Bus). 
port (input) The OID of a Port (Scalar, Bundle, or Bus). 

mode (input) The mode of attachment. Currently, the valid values are CFIDR_ATTACH_BY_ORDER 
and CFIDR_ATTACHJBY_NAME 

error (output) A pointer to the error returned if this function Ms. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
net is not a usable OID. 

CFIDRJNVALIDjOBJECTTYPE: 
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net is not a Net OID. 

CFIDR_UNUSABLE_PORT_OID: 
port is not a usable OID. 

CFIDR_iNVALID_J>ORT_TYPE: 
port is not a Port OID. 

CFIDR.JNVALID _ATTACH JVIODE: 
mode is not a legal AttachMode. 

CFIDRJlEADjONLY: 

the containing View has not been opened for update. 
CFIDR_CROSS_VIEW_OPERATION: 

net and port are not in the same view. They must be in the same view. 
CFEDR_SCALAR_J3UNDLE ATTACHMENT: 

One of net and port is a Scalar, but the other is a Bundles or Bus. PortScalars may not be attached to 
NetBundles or NetBusses. NetScalars may not be attached to PortBundles or PortBusses. 

CFIDR_PORT_ALREADY_ATTACHED: 
port is already attached to a net. 

CFTDR_NO_NAME_MATCHES : 

mode is BY_NAME but no names in the PortBundle match any names in the NetBundle or the 
PortScalar and NetScalar have different names. 

NOTE: This is not necessarily an error—bundles can be connected if previous scalars were connected 
but no new scalars are connected when this occurs. If the bundles were not previously connected, they 
will remain un-connected when this occurs. 

CFIDR_JNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDRJMO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

net = NetBundle, port = PortBundle 

Description: Attempts to attach the PortBundle to the NetBundle's Ports relationship (i.e., connects the 
PortBundle and NetBundle). This is done by downward recursively trying to attach the members until 
eventually scalars are attached. Then bundles are recursively attached upward whenever one or more 
members are attached. The mode argument must be either CFIDR_ATTACHJBY_NAME or 
CFIDR_ATTACH JBY_ORDER. 

CFIDR_ATTACH_BY_ORDER: 

Attaching "by order" takes the ordered list of Nets contained by the NetBundle (or NetBus) and attempts 
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to connect them one-by-one in increasing order of position to the Ports owned by the PortBundle (or 
PortBus). These connection attempts continue until one of the lists is exhausted. It is not an error for the 
lists to be of differing size. 

If a given position in the NetBundle contains a NetBundle but the same position in the PortBundle 
contains a PortScalar or if the NetBundle contains a NetScalar while the PortBundle contains a 
PortBundle, an error code (CFIDRJSCALARJBUNDLE .ATTACHMENT) is returned and no 
connections are made. 

If at a given position there is a NetScalar and a corresponding PortScalar then an attempt is made to 
connect them. That is the Id of the NetScalar becomes the value of the NetScalar attribute of the 
PortScalar (if there was not already another NetScalar connected) and the Id of the PortScalar is added 
to the set of PortScalars on the PortScalars attribute of the NetScalar. If the PortScalar is already 
connected (i.e., its NetScalar attribute is not Null) then an error code 
(CFIDR w .PORT_A-LREADY_ATTACHED) is returned and no connections are made. 

If at a given position there is a Netbundle and a corresponding PortBundle then cfidrNetAttachPortO is 
recursively called with that NetBundle and PortBundle and morfe=CFIDR_ATTACHJBY_ORDER. 
Note that recursive connections are "depth-first." 

Either recursive calls are successful or no connections are made. 

CFIDR_ATTACH J5Y_NAME: 

Attaching "by name" takes each Port owned by the PortBundle and attempts to connect it to the first Net 
contained in the NetBundle which has the same Name attribute. If a corresponding Name is not found 
then this Port is not connected and the next Port in the list is considered. If the corresponding Name is 
found but the type is incompatible (i.e., one is a Scalar but the other is a Bundle or Bus) an error 
(CFIDR_SCALAR_BUNDLE .ATTACHMENT) is returned and no connections are made. 

If the corresponding Name is found and it is for a NetScalar and a PortScalar then an attempt is made to 
connect them. Connecting them means that the Id of the NetScalar becomes die value of the NetScalar 
attribute of the PortScalar (if there was not already another NetScalar connected) and the Id of the 
PortScalar is added to the set of PortScalars on the PortScalars attribute of the NetScalar. However, if 
the PortScalar is already connected (i.e., its NetScalar attribute is not Null) then an error code 
(CFIDR_PORT_ALREADY_ATTACHED) is returned and no connections are made. 

If, for a given Name, there is both a Netbundle and a corresponding PortBundle then 
CfidrNetAttachPortO is recursively called with that NetBundle and PortBundle and 
mo</e=CFIDRjVTTACHJBYJ^AME. Note that these recursive connections are "depth-first." 

Either all recursive calls are successful or no connections are made. v 

Attaching a NetScalar to a PortScalar also implicitly connects the NetBundle containing the NetScalar to 
the PortBundle owning the PortScalar (i.e, the NetBundle's Ports attribute has the PortBundle added to 
it). This implicit connection is made for each NetBundle that contains the NetScalar— remembering that 
a NetScalar can belong to many NetBundles. 

Policy: A PortBundle is attached to a NetBundle if and only if at least one PortScalar (in the 
PortBundle) and NetScalar (in the NetBundle) are attached. 

Rationale: By creating this static requirement in the information model, bundle attachment is defined 
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unambiguously. 

Policy: None of the PortScalars owned by the PortBundle can be already connected to any other 
NetScalar. 

Rationale: a PortScalar connects to at most one NetScalar. 
net = NetScalar, port = PortScalar 

Description: If there are no errors: sets the NetScalar attribute of port to net and adds port to the net's 
Porte attribute (i.e., connects the PortScalar and NetScalar). The mode argument has the following 
meaning: BY__NAME means the connection occurs only if the net and port have the same name. 
BY_ORDER allows the connection regardless of name assuming no other rules are violated. Note that 
multiple PortScalars on a NetScalar means that the PortScalars are "shorted" and at the next level up in 
the hierarchy NetScalars will be aliased as a result of the connection between the corresponding 
PortlnstScalars. 

Policy: The PortScalar cannot be already connected to another NetScalar. 

Policy: Attaching a PortScalar owned by the NetlistView to a NetScalar not contained by a NetBundle is 
allowed. 

Policy: If the attachment is finally allowed between a Port and a Net that are each owned by a Bundle, 
men the owning PortBundle is added implicitly to the Ports relationship of each NetBundle containing 

the ^iet. 

NOTE: to be consistent with this automatic connection of Bundles, it is also necessary that, if a new 
NetBundle is created which includes a Net that is already attached to a Port which is a member of a 
PortBundle, the NetBundle and PortBundle will also be automatically connected. 

Rationale: This relationship denotes that at least one of the PortScalars owned by the PortBundle is 
connected to one of the NetScalars contained by the NetBundle. 

POST-CONDITIONS 

Depending upon the OIDs input and their ownership, implicit relationships may be created between 
PortBundles/PortScalars and NetBundles/NetScalars. The policies defined in the Pre-Conditions section 
outline all of these scenarios. 

If net and port are Bundles, some members of either bundle may not be attached after the function is 
executed due to either name mismatches or there being more members in one Bundle than in the other. 
This is NOT an error condition. 

The updated objects must be saved in order to be persistent. Purging the objects before saving them will 
result in the loss of the changes. 



5-7.2 cfidrNetAttachPortlnst 

DECLARATION 
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cfidrVoidT cfidrNetAttachPortInst( 
cfidrNetldT net, 
cfidrPortlnstldT portlnst, 
cfidrAttachModeT mode, 
cfidrErrorT *error) 

DESCRIPTION 

This fiinction connects the specified net and portlnst. If there are no errors it adds portlnst to the 
Portlnsts attribute of net and either sets the NetScalar attribute of portlnst to net when both are Scalar or 
adds net to the NetBundles attribute of portlnst when both are Bundles (or Busses). 

RATIONALE 

This function only directly attaches Scalars. It also "power" connects members of Bundles while 
recursively traversing the bundle hierarchy. NetBundle to PortlnstBundle connection is an indirect effect 
of connections of members of those bundles ultimately due to some underlying Scalar connection. 

PARAMETERS 

net (input) The OID of a Net to whose Portlnsts relationship portlnst is to be added to. 
portlnst (input) The OID of a Portlnst to add to the Portlnsts relationship. 

mode (input) The mode of attachment. Currently, the valid values are CFIDR_ATTACHJ3Y_ORDER 
and CFIDR_ATTACH_BY_NAME. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR^UNUSABLEjOID: 
net is not a usable OID. 

CFIDRJNVALIDjOBJECTTYPE: 
net is not a Net OID. 

CFIDR_UNUSABLEJPORTINST_OID: 
portlnst is not a usable OID. 

CFIDRJNVALID JPORTINST_TYPE: 
portlnst is not a Portlnst OID. 

CFIDRJNVALID_j\TTACH_MODE: 
mode is not a legal AttachMode. 

CFIDR_READ_ONLY: 

the containing View has not been opened for update. 
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CFIDR^CROSSJVaEW^OPERATION: 

net and portlnst are not in the same view. They must be in the same view. 
CFIDR__SCALAR_BUNDLE_ATTACHMENT: 

One of net and portlnst is a Scalar, but the other is a Bundles or Bus. PortlnstScalars may not be 
attached to NetBundles or NetBusses. NetScalars may not be attached to PortlnstBundles or 
PortlnstBusses. 

CFIDR^PORTINST_ALREADY_ATT ACHED: 
portlnst is already attached to a net 

CFIDFLNO^NAME^MATCHES: 

mode is BYJNAME but no names in the PortlnstBundle match any names in the NetBundle or the 
PortlnstScalar and NetScalar have different names. 

NOTE: This is not necessarily an error— bundles can be connected if previous scalars were connected 
but no new scalars are connected when this occurs. If the bundles were not previously connected, they 
will remain unconnected when this occurs. 

CFIDRJNTERNALJSYSTENtERROR: 
some other error occurred* 

CFIDRJSTOJERROR: 
no error occurred. 

PRE-CONDITIONS 



net = NetBundle, port = PortlnstBundle 

Description: Attaches the PortlnstBundle to the NetBundle's Portlnsts relationship (i.e., connects the 
PortlnstBundle and NetBundle). The mode argument must be either CFIDR^ATTACHJBY NAME or 
CFIDR^TTACHJBYjORDER. 

CFlDPLATTACHJBY_ORDER: 

Attaching "by order" takes the ordered list of Nets contained by the NetBundle (or NetBus) and attempts 
to connect them one-by-one in increasing order of position to the ordered list of Portlnsts owned by the 
PortlnstBundle (or PortlnstBus). These connection attempts continue until one of the lists is exhausted. 
It is not an error for the lists to be of differing size. 

If a given position in the NetBundle contains a NetBundle but the same position in the PortlnstBundle 
contains a PortlnstScalar or if the NetBundle contains a NetScalar while the PortlnstBundle contains a 
PortlnstBundle, an error code (CFIDR^SCALAR^UNDLE^ATTACHMENT) is returned and no 
connections are made. 

If at a given position there is a NetScalar and a corresponding PortlnstScalar then an attempt is made to 
connect them. That is the Id of the NetScalar becomes the value of the NetScalar attribute of the 
PortlnstScalar (if there was not already another NetScalar connected) and the Id of the PortlnstScalar is 
added to the set of PortlnstScalars on the PortlnstScalars attribute of the NetScalar. If the PortlnstScalar 
is already connected (i.e., its NetScalar attribute is not Null) then an error code 
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(CFIDR_PORT_j\LREADY_jVrT ACHED) is returned and no connections are made. 

If at a given position there is a Netbundle and a corresponding PortlnstBundle then 
cfidrNetAttachPortlnstO is recursively called with that NetBundle and PortlnstBundle and 
mo^e=CFIDR_ATTACHJBY_ORDER. Note that recursive connections are "depth-first." 

CFIDR_ATTACH_BY JVAME. 

Attaching "by name" takes each Portlnst owned by the PortlnstBundle and attempts to connect it to the 
first Net contained in the NetBundle which has the same Name attribute. If a corresponding Name is not 
found then this Portlnst is not connected and the next Portlnst in the list is considered. If the 
corresponding Name is found but the type is incompatible (i.e., one is a Scalar but the other is a Bundle 
or Bus) an error (CFIDR_SCALAR_BUNDLE_ATTACHMENT) is returned and no connections are 
made. 

If the corresponding Name is found and it is for a NetScalar and a PortlnstScalar then an attempt is made 
to connect them. Connecting them means that the Id of the NetScalar becomes the value of the 
NetScalar attribute of the PortlnstScalar (if there was not already another NetScalar connected) and the 
Id of the PortlnstScalar is added to the set of PortlnstScalars on the PortlnstScalars attribute of the 
NetScalar. However, if the PortlnstScalar is already connected (i.e., its NetScalar attribute is not Null) 
then an error code (CFIDR_J > ORT_ALREADY^ATT ACHED) is returned and no connections are made. 

If, for a given Name, there is both a Netbundle and a corresponding PortlnstBundle then 
cfidrNetAttachPortlnstO is recursively called with that NetBundle and PortlnstBundle and mode= 
CFIDR_ATTACH_BY_>JAME. Note that these recursive connections are "depth-first." 

Attaching a NetScalar to a PortlnstScalar also implicitly connects the NetBundle containing the 
NetScalar to the PortlnstBundle owning the PortlnstScalar (i.e, the NetBundle's Portlnsts attribute has 
the PortlnstBundle added to it). This implicit connection is made for each NetBundle that contains the 
NetScalar— remembering that a NetScalar can belong to many NetBundles. 

Policy: A PortlnstBundle is attached to a NetBundle if and only if at least one PortlnstScalar (in the 
PortlnstBundle) and NetScalar (in the NetBundle) are attached. 

Rationale: By creating this static requirement in the information model, bundle attachment is defined 
unambiguously. 

Policy: None of the PortlnstScalars owned by the PortlnstBundle can be already connected to any other 
NetScalar. 

Rationale: a PortlnstScalar connects to at most one NetScalar. 
net = NetScalar, port = PortlnstScalar 

Description: If there are no errors: sets the NetScalar attribute of port to net and adds port to the nets 
Portlnsts attribute (i.e., connects the PortlnstScalar and NetScalar). The mode argument has the 
following meaning: CFIDR^ATTACH_B Y_NAME means the connection occurs only if the net and 
port have the same name. CFIDR_ATTACH_BY_ORDER allows the connection regardless of name, 
assuming no other rules are violated. 

Policy: The PortlnstScalar cannot be already connected to another NetScalar. 

Policy: Attaching a PortlnstScalar to a NetScalar not contained by a NetBundle is allowed. 
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Policy: if the attachment is finally allowed between a Portlnst and a Net that are each owned by a 
Bundle, then the owning PortlnstBundle is added implicitly to the Portlnsts relationship of each 
NetBundle containing the Net. 

NOTE: To be consistent with this automatic connection of Bundles, it is also necessary that if a new 
NetBundle is created which includes a Net that is already attached to a Portlnst which is a member of a 
PortlnstBundle, the NetBundle and PortlnstBundle will also be automatically connected. 

Rationale: This relationship occurs if at least one of the Portlnsts owned by the PortlnstBundle is 
connected to one of the Nets contained by the NetBundle. 

POST-CONDITIONS 

Depending upon the OIDs input and their ownership, implicit relationships may be created between 
PortlnstBundles/PortlnstScalars and NetBundles/NetScalars. The policies defined in the Pre-Conditions 
section outline all of these scenarios. 

If net and/wtlnst are Bundles, some members of either bundle may not be attached after the function is 
executed due to either name mismatches or there being more members in one Bundle than in the other 
This is NOT an error condition. 

The updated objects must be saved in order to be persistent. Purging the objects before saving it will 
result in the loss of the changes. J 

5.7.3 cfidrNetBundleFindNetByName 

DECLARATION 

cfidrNetldT cfidrNetBundleFindNetByName( 
cfidrNetBundleldT netBundle, 
cfidrStringT name, 
cfidrErroiT *error) 

DESCRIPTION 

This function returns the Net with the specified name if it is within the Nets relationship defined for the 
NetBundle specified by netBundle. 

RETURN VALUE 

The return value is a cfidrNetldT referring to the Net just found. If an error occurs, a Null OID is 
returned. 

PARAMETERS 

netBundle (input) The OID of the NetBundle in which the Net is to be found, 
name (input) The name of the Net 
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error (output) A pointer to the error returned if this function fails. The caller is responsible for allocatii 
memory for this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
netBundle is not a usable OID. 

CFroRjnsrVALID_OBJECTTYPE: 
netBundle is not the OID of a NetBundle. 

CFIDR_INVALIDjvfAME: 

the name parameter is not a valid string or is not a legal name. 

CFIDR_OBJECT_NOTJFOUND: 
no Net with the specified name exists. 

CFIDR_INTERNAL_SYSTEVLERROR: 
some other error occurred. 

CFIDR_NOJERROR: 
no error occurred. 

PRECONDITIONS 

Only one level down in the specified netBundle is considered when searching for the Net with the 
specified name. Even if there is a Net elsewhere in the NetlistView (including in a lower level bundle) 
with the specified name it will only be returned by this function if it is in the specific netBundle. If the 
Net is to be returned regardless of which (if any) NetBundle contains it, the function 
cfidrNetlistViewFmdNetByNameO should be used. 

POST-CONDITIONS 

Note that a Net can appear at more than one position in a given NetBundle but since this is the exact 
same net regardless of position, it is meaningless to ask which position is returned. 

REFERENCE 

CfidrNetlistViewFmdNetByNameO 



5.7.4 cfidrNetBundleFindNetByPosition 

cfidrNetldT cfidrNetBundleFindNetByPosition( 
cfidrNetBundleldT netBundle, 
cfidrInt32T position 
cfidrErrorT *error) 

DESCRIPTION 
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pis function returns the Net at the specified position within the specified netBundle. The "leftmost" or 
first position is numbered 0 and the "rightmost" or last position is numbered one less than the size of the 
bundle. 

RETURN VALUE 

The return value is a cfidrNetldT referring to the Net just found. If an error occurs, a Null OID is 
returned. 

PARAMETERS 

netBundle (input) The OID of the NetBundle being accessed. 

position (input) The position of the returned Net in the NetBundle. A value of 0 will return the Net at the 
first position. A value one less than the size of the bundle will return the Net at the last position. A value 
greater than or equal to the size of the bundle or any negative value will cause an error. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 6 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
netBundle is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
netBundle is not the OID of a NetBundle. 

CFIDR_rNVALID_POSmON: 

the position parameter is not in the range 0 to one less than the size of the bundle. 

CFIDR_INTERNAL_SYSTEM - ERROR: 
some other error occurred. 

CFIDR_NOJERROR: 
no error occurred. 

PRE-CONDITIONS 

Position of a Net in a NetBundle is determined by the use of the function cfidrNetBundlelnsertNetO 
for this net and subsequently any nets at lower positions (to the left of it). It will also be affected by the 
use of the function cfidrNetBundleRemoveNetO on any nets at lower positions. 

REFERENCE 

cfidrNetBundlelnsertNetO 
CfidrNetBundleRemoveNetO 



5.7.5 cfidrNetBundleGetNets 
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DECLARATION 

cfidrNetsWT cfidrNetBundleGetNets( 
cfidrNetBundleldT netBundle, 
cfidrlterModeT mode, 
cfidrErrorT *error) 

DESCRIPTION 

This function initiates a traversal of all of the Nets (NetBundles, NetBusses, or NetScalars) at the end of 
the Nets relationship defined for the NetBundle specified by netBundle. These are also known as the 
members of the NetBundle. 

RETURN VALUE 

The return value is a cfidrNetsWT referring to an Iterator ID that iterates over Nets. A valid Iterator ID is 
always returned, even when an error occurs. In the case of an error, calling the cfidrlterNextNetO 
function returns a Null OID. 

PARAMETERS 

netBundle (input) The OID of an NetBundle for which the Nets relationship is to be traversed. 

mode (input) The mode that determines which Nets are returned. The current valid values are 
CFIDRJTER_SCALARS, CFIDRJTERJBUNDLES, CFIDRJTERTOP, and CFIDR_ITER_ALL 
See the Pre-Conditions below for more detail on how these modes behave. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
netBundle is not a usable OID. 

CFIDR_JNVALID_OBJECTTYPE: 
netBundle is not the OID of a NetBundle. 

CFIDR_INVALID_ITERMODE: 
mode is not a valid IterMode. 

CFIDRJNTERNAL_SYSTEH_ERROR: 
some other error occurred. 

CFIDR_N0LERROR: 
no error occurred. 

PRE-CONDITIONS 

Returns selected Nets contained by the NetBundle. Nets contained in a NetBundle need not be unique. 
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Thus, the same Net may be produced two or more times for any given NetBundle. 

The order of the Nets on the Nets list of a given NetBundle is determined by the order and positions in 
which Nets are inserted mto that NetBundle as well as by the removal of Nets from that NetBundle. See 
the tunctions cfidrNetBundlelnsertNetO and cfidrNetBundleRemoveNetO. 

The specific Nets returned depend on the mode argument specified: 

/wode=CFIDIUTEIL.TOP 

Returns the Nets directly contained in netBundle. 

worfe=CFIDR_ITER_SCALARS 

Returns all the NetScalars contained directly or recursively in netBundle, whether they are also 
contained in another NetBundle. No NetBundles are output with this mode, only NetScalars. This mode 
lets the application effectively see netBundle flattened to a list of NetScalars "below it". 

morfe=CFIDRJTERJBUNDLES 

Returns all the NetBundles contained directly or recursively in netBundle. No NetScalars are output. 
JM0£fe=CFIDR_ITER _ALL 

Returns all the Nets (NetBundles, NetBusses, or NetScalars) contained directly or recursively in 
netBundle. This mode differs from CFIDR_JTER_TOP in that NetScalars contained in a NetBundle are 
also returned. This mode is a combination of the SCALARS and BUNDLES modes. 

Depth-first recursion is used for all modes except CFIDR_ITER_TOP, which uses no recursion. 
POST-CONDITIONS 

The cfidrlterNexCNetO function returns the next Net OID in the Nets relationship. The next Net 
returned must obey the return mode as specified via the mode argument 

If no objects are currently present in the Nets relationship given the specified mode, an error is not 
returned but the first call to cfidrlterNextNetQ returns a Null OID. 

REFERENCE 

cfidrlterNextNetO 
cfidrNetBundlelnsertNetO 
cfidrNetBundleRemoveNetO 
cfidrNetlistViewCreateNetBundleO 



5.7.6 cfidrNetBundleGetSize 

cfidrInt32T cfidrNetBundleGetSize( 
cfidrNetBundleldT netBundle, 
cfidrErrorT *error) 

DESCRIPTION 
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This function returns the number of Nets currently in the specified netBundle. This is only the number at 
the next level and not a count of the total number of scalars including those indirectly in this bundle 
This is not the number of unique nets; if a Net is in the bundle more than once, each position of that Net 
contributes to the total size. 

RETURN VALUE 
The return value is a cfidrInt32T. If an error occurs, a -1 is returned. 

PARAMETERS 
netBundle (input) The OID of a NetBundle. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
netBundle is not a usable OID. 

CFIDRJNVALIDjOBJECTTYPE: 
netBundle is not the OID of a NetBundle. 

CFIDR_JNTERNAL_SYSTEM JERROR: 
some other error occurred. 

CFIDR_NOJERROR: 
no error occurred. 

PRE-CONDITIONS 

NetBundles are created with size 0. Members are added via the cfidrNetBundlelnsertNetO function 
and removed with the CfidrNetBundleRemoveNetO function. 

REFERENCE 

cfidrNetBundlelnsertNetO 

cfidrNetBundleRemoveNetO 

cfidrNetlistViewCreateNetBundleO 

5.7.7 cfidrNetBundlelnsertNet 

DECLARATION 

cfidrVoidT cfidrNetBundleInsertNet( 
cfidrNetBundleldT netBundle, 
cfidrNetldTnet, 
cfidrInt32T position, 
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cfidrErrorT *enor) 
DESCRIPTION 

This function inserts the existing net (NetBundle, NetBus, or NetScalar) in the NetBundle specified by 
netBundle at the position specified by position. 

PARAMETERS 

netBundle (input) The OID of the NetBundle into whose list of Nets net is being inserted, 
net (input) The OID of the Net to be inserted into the NetBundle. 

position (input) The desired location of the Net in the NetBundle. If position is less than 0 or greater 
than or equal to the number of members in the list of Nets in the NetBundle netBundle, the new Net is 
appended as the last member of the list Otherwise, it is inserted at the specified position in the list (0 is 
the first or "leftmost'' position). 



error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
memory for this parameter. 6 

ERROR CODES 



CFIDRJJNUSABLE_OID: 
netBundle is not a usable OID. 



CFIDR_JNVALID_OBJECTTYPE: 

netBundle is not the OID of a NetBundle or a Net Bus. 

CFIDR_UNUSABLE_NET_OID: 
net is not a usable OID. 



CFIDR_INVALID_NET_TYPE: 

the net OID refers to an OID of an inappropriate type. 

CFIDR_CROSS_VIEW_OPERATION: 

the NetBundle netBundle and the Net net are owned by different Views. 

CFIDRJvlEMBER JRECURSION: 

the netBundle and net OIDs refer to the same object. 

CFIDR_READ_ONLY: 

the containing View has not been opened for update. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred 

CFIDR_NO_ERROR: 
no error occurred. 
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PRE-CONDITIONS 

The NetBundle netBundle and Net net to be added must both be owned by the same View. 

The netBundle and net OIDs cannot refer to the same object since this would result in recursion. 
Checking for recursion via multiple levels of Bundle containment is encouraged but not required. 

POST-CONDITIONS 

The Net is added to the list of Nets owned by netBundle at position. If position=0, the new Net will be 
added as the first member of the list. If position is less than 0 or greater than or equal to the number of 
members in the list, the Net is appended to the end of the list Otherwise, the Net is inserted at the 
specified position (0 based). The position of all members whose positions were greater than or equal to 
position, will have their position incremented by 1 . 

For example, presume a NetBundle has members: 
A, B, CO, 1,2. 

Adding a new member X at position 1 results in: 
A,X,B,C0, 1,2 

Note that adding X at position 0 is inserting at the beginning: 
X,A,B,C0,1,2 

and adding at an invalid position such as -1 causes the new member to be appended at the end- 
A, B, CO, 1, 2, X 

REFERENCE 

cfidrNetBundleRemoveNetO 
cfidrNetBundleGetNetsO 
cfidrNetiistViewCreateNetBundleO 
cfidrNetlistViewGetNetsO 

5.7.8 cfidrNetBundleRemoveNet 

DECLARATION 

cfidrVoidT cfidrNetBundleRemoveNet( 
cfidrNetBundleldT netBundle, 
cfidr!nt32T position, 
cfidrErrorT *error) 

DESCRIPTION 

This function removes a Net at position from a NetBundle (or NetBus). 
PARAMETERS 



http://ww.si2.org/si2^ublicauons/hm^ 



6/23/2004 



Page 52 of 89 



netBundle (input) The OID of the parent NetBundle (or NetBus). 

position (input) The location of the Net to be removed from netBundle. If position is less than 0 or 
greater than or equal to the size of the list of Nets in netBundle, an error is returned. Otherwise, the net 
at the specified position is removed (0 is the first member). 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
memory for this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
netBundle is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 

netBundle is not the OID of a NetBundle or NetBus. 

CFIDRJNVALID .POSITION: 

the position specified is less than 0 or greater than or equal to the size of the list of Nets in the 

NetBundle. Note that legal positions range from 0 to 

size-1. 

CFIDR_READ_ONLY: 

the containing View has not been opened for update. 

CFIDRJNTERNAL_S YSTEM JBRROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

The specified position must identify a net in the NetBundle netBundle. 
POST-CONDITIONS 

The Net at the specified position in the NetBundle will be removed from the list of members of 
netBundle. It is not deleted from the View or removed from membership in any other NetBundles (or 
NetBusses) or from any other position within this NetBundle. 

All other members of the NetBundle with position values greater than the value held by the Net at 
position will have their position values decremented by one. That is, ordering of the remaining members 
Nets within the NetBundle will be preserved and the positions will start from zero and monotonically 
increase by one with no gaps. 

For example, presume a NetBundle has members: 
A, B, CO, 1, 2. 
at positions: 
0,1,2,3,4 
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Removing the member at position=l (i.e., "B") results in- 
A, CO, 1,2 
at positions: 
0,1,2,3 

REFERENCE 

cfidrNetBundlelnsertNetO 
cfidrNetBundleGetNetsO 
cfidrNetlistViewCreateNetBundleO 
cfidrNetlistViewGetNetsO 



5.7.9 cfidrNetBusGetStart 

DECLARATION 

cfidrint32T cfidrNetBusGetStart( 
cfidrNetBusIdT netBus, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the start attribute of the specified netBus. This specifies the first index value for 
this bus. 

RETURN VALUE 

The return value is a cfidrInt32T. If an error occurs, a 0 is returned. 

PARAMETERS 
netBus (input) The OID of a NetBus. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
me memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
netBus is not a usable OID. 

CFTDRJNVALIDjOBJECTTYPE: 
netBus is not the OID of a NetBus. 

CFIDRJNTERNAL_SYSTEMJERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 
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PRE-CONDITIONS 

The value of the Start attribute of a NetBus is determined at creation time or via the 
cfidrNetBusSetStartO function. 

REFERENCE 

CfidrNetBusSetStartO 
cfidrNetlistViewCreateNetBusO 

5.7.10 cfidrNetBusGetStep 

DECLARATION 

cfidrInt32T cfidrNetBusGetStep( 
cfidrNetBusIdT netBus, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the Step attribute of the specified netBus. This specifies the numeric increment 
between positions for the index. 

RETURN VALUE 

The return value is a cfidrInt32T. If an error occurs, a 0 is returned. 

PARAMETERS 
netBus (input) The OID of a NetBus. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDRJJNUSABLE_OID: 
netBus is not a usable OID. 

CFroR_INVALID_OBJECTTYPE: 
netBus is not the OID of a NetBus. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDRJSIOJSRROR: 
no error occurred. 

PRE-CONDITIONS 
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The value of the Step attribute of a NetBus is determined at creation time or by the use of the 
cfidrNctBusSctStcpO function. 

REFERENCE 
cfidrNetBusSetStepO 



5.7.11 cfidrNetBusSetStart 

DECLARATION 

cfidrVoidT cfidrNetBusSetStart( 
cfidrNetBusIdT netBus, 
cfidrInt32T start, 
cfidrErrorT *error) 

DESCRIPTION 

This function sets the Start attribute of the specified netBus to start. This specifies the index value for 
position 0 in this bus. 

PARAMETERS 

netBus (input) The OID of a NetBus. 

start (input) The 32 bit integer number for position 0 which is the first (leftmost) index of the bus. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
netBus is not a usable OID. 

CFIDRJNVALID_OBJECTTYPE: 
netBus is not the OID of a NetBus. 

CFIDR_READ_ONLY: 

the containing View has not been opened for update. 

CFIDR_JNTERNAL_SYSTEMJERROR: 
some other error occurred. 

CFIDRJJOJERROR: 
no error occurred. 

POST-CONDITIONS 



http://ww.si2.org/si2jublications/htalSpecs/DR/part5a.fm4A 



6/23/2004 



Page 56 of 89 



The index of position 0 is now start. 
REFERENCE 

cfidrNetBusGetStartO 
cfidrNetlistViewCreateNetBusO 



5.7.12 cfidrNetBusSetStep 

DECLARATION 

cfidrVoidT cfidrNetBusSetStep( 
cfidrNetBusIdT netBus, 
cfidrInt32T step, 
cfidrErroiT *error) 

DESCRIPTION 

This function sets the Step attribute of the specified netBus to step. This specifies the numeric increment 
between positions by which the index changes. 

PARAMETERS 

netBus (input) The OID of a NetBus. 

step (input) The 32 bit integer number for the step. This number must be non-zero. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
die memory used by this parameter. 

ERROR CODES 

CFIDRJJNUS ABLE_OID : 
netBus is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
netBus is not the OID of a NetBus. 

CFIDR_INVALID_VALUE: 
step is zero. 

CFIDR_jREAD_ONLY: 

the containing View has not been opened for update. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 
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POST-CONDITIONS 

The difference in index values of positions n and n+1 will be step after the execution of this function. 
REFERENCE 

cfidrNetBusGetStepO 
cfidrNetlistViewCreateNetBusQ 



5.7.13 cfidrNetDetachPort 

DECLARATION 

cfidrVoidT cfidrNetDetachPort 
cfidrNetldT net, 
cfidrPortldT port, 
cfidrErrorT *error) 

DESCRIPTION 

This function detaches (removes) the Port specified via port fiom the Ports relationship defined for the 
Net specified via net. 

PARAMETERS 

net (input) The OID of a Net from whose Ports relationship port is to be removed from. 
port (input) The OID of a Port to remove from the Ports relationship. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
net is not a usable OID. 

CFIDR^INVALIDjOB JECTTYPE: 
net is not the OID of a Net 

CFIDR_UNUSABLE_J»ORT_OID: 
port is not a usable OID. 

CFIDRJNVALID_PORT_TYPE: 
port is not a Port OID. 

CFIDRJ>ORT_NOT_ATTACHED: 

port is not attached to net This code is also returned when net is a bundle but port is a scalar or net is a 
scalar and port is a bundle since these can never be attached. 
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CFIDR JtEAD_ONLY: 

the containing View has not been opened for update. 

CFIDR_JNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NOJERROR: 
no error occurred. 

PRE-CONDITIONS 



net = NetBundle, port = PortBundle 

Description: Detaches (removes) the PortBundle from the NetBundle's Ports relationship (i.e., 
disconnects the PortBundle and NetBundle). Likewise, any PortScalars owned by the PortBundle are 
detached from their connected NetScalar's Ports relationship. See the discussion, "NetBundle 
C onnection to PQ rtfJnsflBjmdJeJsaDerived Relationshi p " on page4z35, for additional implications. 

NOTE: The only PortScalars detached are those connected to NetScalars which are contained in the 
NetBundle specified via net. Other PortScalars owned by the PortBundle specified vi&port may be 
connected to NetScalars not contained in the NetBundle specified via net. 

Policy: A PortBundle remains attached to a NetBundle if and only if at least one PortScalar (in (he 
PortBundle) and NetScalar (in the NetBundle) are attached. 

Rationale: By creating this static requirement in the information model bundle attachment is defined 
unambiguously. 

net = NetScalar, port ■ PortScalar 

Description: Detaches (removes) the PortScalar from the NetScalar's Ports relationship. 

Policy: If both the NetScalar and PortScalar are owned by appropriate Bundles, the PortBundle is 
likewise detached from the NetBundle if this is the last Scalar attachment being removed between the 
Bundles. 

Rationale: There is no need to keep the NetBundle/PortBundle relationship around since it is 
automatically created if and when the Scalars attach again. 

POST-CONDITIONS 

Several relationships may be implicitly removed depending upon the input arguments.The policies 
defined in the Pre-Conditions section outline all of these scenarios. 

The updated objects must be saved in order to be persistent Purging the objects before saving it will 
result in the loss of the changes. 

See the discussion, "NetBundle Connection to PortfInst]Bundle is a Derived Relationship" on pag e 4-35 . 
for additional implications. 
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REFERENCE 
cfidrNetAttachPortO. 



5.7.14 cfidrNetDetachPortlnst 

DECLARATION 

cfidrVoidT cfidrNetDetachPortInst( 
cfidrNetldTnet, 
cfidrPortlnstldT portlnst, 
cfidrEnorT *error) 

DESCRIPTION 

This function detaches (removes) the Portlnst specified via portlnst from the Portlnsts relationship 
defined for the Net specified via net. 

PARAMETERS 

net (input) The OID of a Net from whose Portlnsts relationship portlnst is to be removed. 

portlnst (input) The OID of a Portlnst to remove from the Portlnsts relationship. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDRJUNUSABLEjOID: 
net is not a usable OID. 

CFroRJNVALIDjOBJECTTYPE: 
net is not the OID of a Net 

CFIDR w UNUSABLE_PORTINST_OID: 
portlnst is not a usable OID. 

CFIDRJNVALID_P0RTINST_TYPE: 
portlnst is not a Portlnst OID. 

CFIDR_READ_ONLY: 

the containing View has not been opened for update. 
CFlDRJ>ORTINST_NOT_ATTACHED: 

portlnst is not attached to net This code is also returned when net is a bundle but port is a scalar or net is 
a scalar and port is a bundle since these can never be attached. 

CFIDR_JNTERNAL_SYSTEMJERROR: 
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some other error occurred. 

CFIDR_NQJiRROR: 
no error occurred. 

PRE-CONDITIONS 



ne/ = NetBundle,/«?r///ts/ = PortInstBundle 

Description: Detaches (removes) the PortlnstBundle from the NetBundle's Portlnsts relationship (i e 
disconnects Ae PortlnstBundle and NetBundle). Likewise, any PortlnstScalars owned by the 
PortlnstBundle are detached from their connected NetScalar*s Portlnsts relationship. 

m?I E: J* 0nl ^ PortlnstScalars detached are those connected to NetScalars which are contained in the 
NetBundle specified 1 via net. Other PortlnstScalars owned by the PortBundle specified vi&portlnst may 
be connected to NetScalars not contained in the NetBundle specified via object. 

Policy: A PortBundle remains attached to a NetBundle if and only if at least one PortlnstScalar (in 
the PortlnstBundle) and NetScalar(in the NetBundle) are attached. 1 
Rationale: By creating this static requirement in the information model, bundle attachment is defined 
unambiguously. 

net = NetScalar, port/art = PortlnstScalar 

Definition: Detaches (removes) the PortlnstScalar from the NetScalar's Portlnsts relationship. 

Policy: If both the NetScalar and PortlnstScalar are owned by appropriate Bundles, the PortlnstBundle is 
Smdte NetBundle if this is the last Scalar attachment being removed between the 

Rationale: There is no need to keep the NetBundle/PortlnstBundle relationship around since it is 
automatically created if and when the Scalars attach again. 

POST-CONDITIONS 

Several relationships may be implicitly removed depending upon the input arguments/The policies 
defined in the PRE-CONDITIONS section outline all of these scenarios. 

The updated objects must be saved in order to be persistent Purging the objects before saving will result 
in the loss of the changes. 

See the discussion, "NetBundle Connection Pnrtrinct]R,,n^lA ic a Derived Relationship" on pap * d.** 

tor additional implications. 

REFERENCE 
cfidrNetAttachPortlnstO 



5.7.15 cfidrNetFindNetBundleByName 
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DECLARATION 

cfidrNetBundleIdTcfidrNetFindNetBundleByName( 
cfidrNetldT net, 

cfidrStringT name, 

cfidrErrorT *error) 

DESCRIPTION 

This function returns the NetBundle with the specified name that is within the NetBundles relationship 
defined for the Net specified by net 

RATIONALE 

This is a search by name of all the NetBundles of which this Net is a member, a set that can be accessed 
using the cfidrNetGetNetBundlesO function. This is possible because a Net can be in more than one 
NetBundle. 

RETURN VALUE 

The return value is a cfidrNetBundleldT referring to the NetBundle just found. If an error occurs a Null 
OID is returned. 

PARAMETERS 

net (input) The OID of the Net from which the NetBundle is to be found, 
name (input) The name of the NetBundle. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
memory for this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
net is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
net is not the OID of a Net 

CFIDR_INVALID_NAME: 

the name parameter is not a valid string or is not a legal name. 

CFIDR_OBJECT_NOT_FOUND: 

no NetBundle with the specified name exists. 

CFIDRJNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
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no error occurred. 

REFERENCE 

cfidrNetGetNetBundlesQ 



5.7.16 cfidrNetGetNetBundles 

DECLARATION 

cfidrNetBundlesIdT cfidrNetGetNetBundles( 

cfidrNetldTnet, 

cfidrErrorT *error) 

DESCRIPTION 

This function initiates a traversal of all of the NetBundles at the end of the NetBundles relationship 
defined for the Net specified by net. A Net can belong to more than one NetBundle. This function 
returns all the NetBundles of which net is a Member. 

RETURN VALUE 

The return value is a cfidrNetBundlesIdT referring to an Iterator ID that iterates over NetBundles. A 
valid Iterator ID is always returned, even when an error occurs. In the case of an error, calling the 
cfidrlterNextNetBundleO function returns a Null OID. 

PARAMETERS 

net (input) The OID of a Net for which the NetBundles relationship is to be traversed. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
net is not a usable OID. 

CFIDRJNVALID_OBJECTTYPE: 
net is not the OID of a Net. 

CFIDRJNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

POST-CONDITIONS 
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The cfidrlterNextNetBundleO function returns the next NetBundle OID in the NetBundles relationship. 

If no objects are currently present in the NetBundles relationship, an error is not returned but the first 
call to cfidrlterNextNetBundleO returns a Null OID. 

REFERENCE 
cfidrlterNextNetBundleO 

5.7.17 cfidrNetGetOwner 

DECLARATION 

cfidrNetlistViewIdT cfidrNetGetOwner( 
cfidrNetldT net, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the View at the end of the Owner relationship for the Net specified by net. The 
Owner relationship is defined when an object is created and cannot be modified. 

RETURN VALUE 

The return value is a cfidrNetlistViewIdT referring the NetlistView at the end of the Owner relationship. 
If an error occurs, a Null OID is returned. 

PARAMETERS 

net (input) The OID of the Net whose Owner relationship is to be followed. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDRJJNUSABLE_OID: 
net is not a usable OID. 

CFIDRJNVALID_OBJECTTYPE: 
net is not the OID of a Net 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_J}RROR: 
no error occurred. 
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5.7.18 cfidrNetGetPorts 

DECLARATION 

cfidrPortsIdT cfidrNetGetPorts( 
cfidrNetldTnet, 
cfidrErrorT *error) 

DESCRIPTION 

This function initiates a traversal of all of the Ports (PortBundles, PortBusses, or PortScalars) at the end 
of the Ports relationship defined for the Net specified by net. 

RETURN VALUE 

The return value is a cfidrPortsIdT referring to an Iterator ID that iterates over Ports. A valid Iterator ID 
is always returned, even when an error occurs. In the case of an error, calling the cfidrlterNextPortO 
function returns a Null OID. 

t 

PARAMETERS 

net (input) The OID of an object for which the Ports relationship is to be traversed. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFroRJJNUSABLE_OID: 
net is not a usable OID. 

CFIDR_IKVALID_OBJECTTYPE: 
net is not the OID of a Net 

CFIDRJNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDRJSIOJERROR: 
no error occurred. 

PRE-CONDITIONS 

The net parameter may either be a NetScalar, NetBundle, or Netbus. The NetBundle and NetBus behave 
the same for this function. 

NetScalar 

Description: Returns all PortScalars connected by this NetScalar. Note that multiple PortScalars on a 
NetScalar means that the PortScalars are "shorted" and at the next level up in the hierarchy NetScalars 
will be aliased as a result. 
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NetBundle (or NetBus) 

Description: Returns all PortBundles or PortBusses which are connected to the NetBundle (or NetBus). 
See the cfidrNetAttachPortO function for how NetBundles and PortBundles may be connected. All 
PortBundles, which directly or indirectly contain any PortScalars connected to NetScalars owned 
directly or indirectly by net, are returned. 

POST-CONDITIONS 

The cfidrlterNextPortO function returns the next Port OID in the Ports relationship. 

If no objects are currently present in the Ports relationship, an error is not returned but the first call to 
cfidrlterNextPortO returns a Null OID. 

REFERENCE 

cfidrlterNextPortO 
cfidrNetAttachPortO 



5.7.19 cfidrNetGetPortlnsts 

DECLARATION 

cfidrPortlnstsIdT cfidrNetGetPortInsts( 
cfidrNetldT net, 
cfidrErrorT *error) 

DESCRIPTION 

This function initiates a traversal of all of the Portlnsts (PortlnstBundles, PortlnstBusses, or 
PortlnstScalars) at the end of the Portlnsts relationship defined for the Net specified by net. 

RETURN VALUE 

The return value is a cfidrPortlnstsIdT referring to an Iterator ID that iterates over Portlnsts. A valid 
Iterator ID is always returned, even when an error occurs. In the case of an error, calling the 
cfidrlterNextPortlnstO function returns a Null OID. 

PARAMETERS 

net (input) The OID of a Net for which the Portlnsts relationship is to be traversed. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
fee memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
net is not a usable OID. 
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CFIDR_INVALID_OBJECTTYPE: 
net is not the OID of a Net 

CFIDR_INTERNAL_SYSTEMJERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

The net parameter may either be a NetScalar, NetBundle, or Netbus. The NetBundle and NetBus behave 
the same for this function. 

NetScalar 

Description: Returns all PortlnstScalars connected by (his NetScalar. 
NetBundle (or NetBus) 

Description: Returns all PortlnstBundles or PortlnstBusses which are connected to this NetBundle (or 
NetBus). See the c fidrNet Attach Port Ins t() function for how NetB undies and PortlnstBundles may be 
connected. All PortlnstBundles, which directly or indirectly contain any PortlnstScalars connected to 
NetScalars owned directly or indirectly by net, are returned. 

POST-CONDITIONS 

The cfidrlterNextPortlnstO function returns the next Portlnst OID in the Portinsts relationship. 

If no objects are currently present in the Portinsts relationship, an error is not returned but the first call 
to cfidrlterNextPortlnstO returns a Null OID. 

REFERENCE 

cfidrlterNextPortlnstO 
cfidrNetAttachPortlnstO 



5,7.20 cfidrNetScalarGetlsGlobal 

DECLARATION 

cfidrBooleanT cfidrNetScalarGetIsGlobal( 
cfidrNetScalarldT netScalar, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the IsGlobal attribute for the NetScalar specified in netScalar. 
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RETURN VALUE 

The return value is a cfidrBooleanT which specifies whether this NetScalar is a global net. All global 
nets with the same name are the same electrically common net although different OIDs may be used for 
them in different NetlistViews. If an error occurs CFIDR_FALSE is returned. 

PARAMETERS 

netScalar (input) The OID of the NetScalar whose IsGlobal attribute is desired. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocatinc 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
netScalar is not a usable OID. 

CFIDR_JNVALID_OBJECTTYPE: 
netScalar is not the OID of a NetScalar 

CFIDR_JNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

The value of IsGlobal is CFIDR_FALSE when a NetScalar is newly created by 
cfidrNetiistViewCreateNetScalarO It may be set by the function cfidrNetScalarSetlsGlobalO 

REFERENCE 

cfidrNetlistViewCreateNetScalarO 
cfidrNetScalarSetlsGlobalO 



5.7.21 cfidrNetScalarSetlsGlobal 

DECLARATION 

cfidrVoidT cfidrNetScalarSetIsGlobal( 
cfidrNetScalarldT netScalar, 
cfidrBooleanT value 
cfidrErrorT *error) 

DESCRIPTION 

This function sets the IsGlobal attribute for the NetScalar specified in netScalar to the cfidrBooleanT 
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value specified in value. 
PARAMETERS 

netScalar (input) The OID of the NetScalar whose IsGlobal attribute is to be set. 

value (input) The desired cfidrBooleanT value for the IsGlobal attribute of netScalar. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
die memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
netScalar is not a usable OID. 

CFIDRJNVALIDjOBJECTTYPE: 
netScalar is not the OID of a NetScalar 

CFIDR_INVALID_VALUE: 
value is not a valid Boolean value. 

CFIDRJtEADjONLY: 

the containing object (Lib or View) has not been opened for update. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFEDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

The value of IsGlobal is CFIDR_FALSE when a NetScalar is newly created by 
cfidrNetlistViewCreateNetScalarO. It may have been set by previous calls to this function. 

POST-CONDITIONS 

The IsGlobal attribute of netScalar will be value after the execution of this function. That value will be 
persistent after a call to cfidrViewSaveO- Any call to cfidrNetScalarGetlsGlobalO prior to another call 
to cfidrNetScalarSetlsGlobalO will return value unless a call to cfidrViewPurgeO is done before any 
call to cfidrViewSaveO. 

All NetScalars with IsGlobal=CFJDKJR\JE and the same value for Name are considered to be the 
same electrically common scalar net but each NetlistView may return a different OID for its global 
NetScalar by that name. Furthermore, the function cfidrObjectlsSameO will not necessarily return the 
value CFIDRJTRUE when called with two NetScalars from different NetlistViews even though their 
Names are the same and both have IsGlobal set to CFIDRJTRUE. 

REFERENCE 
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cfidrNetScalarGetlsGlobalO 
cfidrObjectlsSameO 
cfidrViewPurgeO 
cfidrViewSaveO 

cfidrNetlistViewCreateNetScalarO 



5.8 Object Functions 



5.8.1 cfidrObjectCreateProp 

DECLARATION 

cfidrPropWT cfidrObjectCreateProp( 
cfidiObjectldT owner, 
cfidrStringT name, 
cfidrErrorT *error 

DESCRIPTION 

This function creates a Property object owned by the object specified via owner. The Name attribute is 
set to name. 

RATIONALE 

This function does not specify the Property's ValueType or Value attributes during creation. If this were 
available, there would be a function for each valueType. To minimize the number of functions, this one 
function to create a named Property with a default Value and ValueType is used. The cfidrPropSet 
{Boolean, Float32, Int32,String} ValueO functions are used to set those values and types after the 
property is created. 

RETURN VALUE 

The return value is a cfidrPropIdT referring to the Property just created. If an error occurs, a Null OID is 
returned. 

PARAMETERS 

owner (input) The OID of the object which will own the created Property. This OID can refer to any 
object, even another Property. 

name (input) The string representing the name of the Property. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 
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CFIDR__UNUSABLE_OID: 
owner is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 

owner is not the OID of an Object which can own properties. 

NOTE: This is not possible at this time since all objects currently can own properties. 
CFIDR_INVALID_NAME: 

the name parameter is not a valid string or is not a legal name. 

CFIDR_OBJECT _ALREADY_EXISTS: 
a prop with the same name already exists. 

CFIDR v _READ_ONLY: 

the containing object (Lib or View) has not been opened for update. 

CFIDRJNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NOJERROR: 
no error occurred. 

PRE-CONDITIONS 

The name argument must conform to the character set rules for name strings. 
POST-CONDITIONS 

The property can later be accessed via its Name attribute by using the cfidrObjectFindPropByNameO 
function. 

REFERENCE 

CfidrObjectFindPropByNameO 
cfidrObjectGetPropsO 



5.8.2 cfidrObjectDestroy 

DECLARATION 

cfidrVoidT cfidrObjectDestroy( 
cfidrObjectldT object, 
cfidrErrorT *error) 

DESCRIPTION 

This function destroys the object specified via object. The effect of destroying an object is to also 
destroy the entire object hierarchy owned by the destroyed object. 
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PARAMETERS 

object (input) The OID of the object to be destroyed. The object hierarchy owned by object is also 
destroyed. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDIUJNUSABLE-OID: 
object is not a usable Off). 

CFIDRJNVALIDjOBJECTTYPE: 

object is not the OID of a destroyable object These are only all the subtypes of Portlnst at this time. 
CFIDRJREADjONLY: 

the containing object (Lib or View) has not been opened for update. Note that the containing object of a 
View is its parent Lib; aView can always be destroyed if its parent Lib is open for update. A Lib or 
SelectorSet can always be destroyed. 

CFIDR_JNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDRJsJOJERROR: 
no error occurred. 

PRE-CONDITIONS 

Since the various subtypes (scalar, bundle, and bus) of Portlnst objects are not created explicitly (they're 
defined automatically when the Inst is created), they cannot be destroyed explicitly. They can only be 
destroyed by destroying the Inst. 

POST-CONDITIONS 

See the discussion, 'TMBundle Co nnection to P ort[Inst]Bundle is a Derived Relationship" on page 4-3S 3 
for additional implications. 

NetScalars 

Destroying a NetScalar removes the NetScalar from each NetBundle that owns the NetScalar 
(preserving the order of the Nets remaining within the NetBundle) and then destroys the actual 
NetScalar object. 

If a NetScalar being destroyed is attached to PortScalars or PortlnstScalars then the NetScalar is first 
detached from those objects and then destroyed. 

NetBundles (and NetBusses) 

If a NetBundle (or NetBus) being destroyed is attached to any PortBundles (or PortBusses) or 
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PortlnstBundles (or PortlnstBusses) by virtue of having NetScalars in the NetBundle attached to 
PortScalars or to PortlnstScalars those PortflnsfJBundles will be detached from the NetBundle before it 
is destroyed. 



Destroying a NetBundle does NOT destroy the Nets contained by the NetBundle because a NetBundle h 
merely a "collector" or "grouper" of Nets and not the owner of those Nets. 

Desfroying a NetBundle does NOT affect any attachment connectivity below it in a hierarchy; however, 
NetBundles above it may be detached if the destroyed bundle represented the last remaining "indirect" 
container of an actual scalar that is connected. (See "Bundle/Scalar Manipulate ™ p » r n ) 

PortScalars 



Destroying a PortScalar first removes it from any PortBundle, detaches the PortScalar from any 
NetScalars, and then finally destroys the actual PortScalar object. 

PortBundles (and PortBusses) 

Destroying a PortBundle (or PortBus) first detaches each and every PortScalar directly or indirectly 
owned by the PortBundle from any attached NetScalars) thereby detaching all PortBundles from any 
NetBundles. Then each Port object (PortBundle, PortBus, or PortScalar) owned by this PortBundle is 
destroyed. The order of detachment or destruction is implementation-dependent 

Views or Ports used as Describers 

Destroying a View or Port that is referenced in another View via the Describer relationship of an Inst or 
Portlnst just breaks the Describer relationship from the Inst or Portlnst. The Inst and Portlnst are not 
themselves destroyed. 

Insts (and Portlnsts) 

Destroying an Inst first detaches each Portlnst (on this Inst) from any Net to which it is attached. The 
Inst is then removed from the list of Insts in the Owner View. Finally the Inst plus all the Portlnsts in the 
Portlnsts list (on this Inst) is destroyed. 

NOTE: This is the only way the Portlnsts may be destroyed. 
Persistence 

Destroying a persistent container object (a Lib, View or SelectorSet) destroys the object itself and all 
contained objects, and all persistent data associated with the object. Destroying any other object does not 
destroy the persistent data associated with that object. The update caused by the destruction must be 
saved (with LibSave, ViewSave, or SelectorSetSave) in order for the persistent data to be destroyed. 

REFERENCE 

cfidrLibSaveO 
cfidrlterNextViewQ 



http://ww.si2.org/si2jublicahons^ 



6/23/2004 



Page 73 of 89 



5.8.3 cfidrObjectFindPropByName 

DECLARATION 

cfidrPropIdT cfidiObjectFindPropByName( 
cfidrObjectldT object, 
cfidrStringT name, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the Prop with the specified name that is within the Props relationship defined for 
the Object specified by object. 

RETURN VALUE 

The return value is a cfidrPropIdT referring to the Prop just found. If an error occurs, a Null OID is 
returned. 

PARAMETERS 

object (input) The OID of the Object from which the Prop is to be found, 
name (input) The name of the Prop. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
memory for this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
object is not a usable OID. 

CFIDR_INVALID_N AME : 

the name parameter is not a valid string or is not a legal name. 

CFIDR_OBJECT_NOT_FOUND: 
no Prop with the specified name exists. 

CFIDRJNTERNALJSYSTEMJERROR: 
some other error occurred. 

CFIDR_NOJ2RROR: 
no error occurred. 



5.8.4 cfidrObjectGetObjectType 

DECLARATION 
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cfidrObjectTypeT cfidrObjectGetObjectType( 
cfidrObjectldT object, 
cfidrErrorT *enor) 

DESCRIPTION 

This function returns the ObjectType attribute for the object specified by object. 
RETURN VALUE 

The return value is the enumerated type cfidrObjectTypeT which knows about all the objects which can 
be created. Currently, this includes only those leaf-level subtypes. If an error occurs, 
CFroRJJNDEFrNED_OBJECTTYPE is returned. 

object (input) The OH) of the object for which the ObjectType attribute is desired. The ObjectType 
attribute exists for the base Object supertype, so all OIDs are valid input arguments, even the Null OID. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
object is not a usable OID. 

CFIDR^JNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_JNO_ERROR: 
no error occurred. 

POST-CONDITIONS 

Passing in a Null ODD will return the CFIDR_UNDEFINED_OBJECTTYPE constant. 
REFERENCE 

The following functions all return objects that need to be further differentiated via the 
cfidrObjectGetObjectTypeO function: 

cfidrCellGetViewsO 

cfidrNetBundleGetNetsO 

cfidrPortGetOwnerO 

cfidrPortBundleGetPortsO 

cfidrPortlnstGetOwnerO 

cfidrPortlnstBundleGetPortlnstsO 

cfidrPropGetOwnerO 

cfidrlterNextNetO 

cfidrlterNextPortO 

cfidrlterNextPortlnstO 
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5.8.5 cfidrObjectGetProps 

DECLARATION 

cfidrPropsIdT cfidrObjectGetProps( 
cfidrObjectldT object, 
cfidrErrorT *enx>r) 

DESCRIPTION 

This function initiates a traversal of all of the Property objects at the end of the Props relationship 
defined for the object specified by object. 

RETURN VALUE 

The return value is a cfidrPropsIdT referring to an Iterator ID that iterates over Property objects. A valid 
Iterator ID is always returned, even when an error occurs. In the case of an error, calling the 
cfidrlterNextPropO function returns a Null OID. 

PARAMETERS 

object (input) The OID of an object for which the Props relationship is to be traversed. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDRJUNUSABLE_OID: 
object is not a usable OID. 

CFIDR w [NTERNAL_SYSTENl_ERROR: 
some other error occurred. 

CFIDR_NOJERROR: 
no error occurred. 

PRECONDITIONS 

Since all objects can have associated Properties (including Properties), this function accepts all usable 
OIDs. 

POST-CONDITIONS 

The cfidrlterNextPropO function returns the next Property OID in the Props relationship. 

If no objects are currently present in the Props relationship, an error is not returned but the first call to 
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cfidrlterNextPropO returns a Null ODD. 
REFERENCE 

cfidrlterNextPropO 



5.8.6 cfidrObjectlsNull 

DECLARATION 

cfidrBooleanT cfidrObjectIsNull( 
cfidrObjectldT object, 
cfidrErrorT *error) 

DESCRIPTION 

This function determines whether the OID specified via object is a Null OID. 

NOTE: This is the only mechanism which should be used to determine whether an OID is the Null OID, 
since different PI implementations may define the Null OID differently. The equality operator, "=" 
should not be used to test for Null. 

RETURN VALUE 

The return value denotes whether or not the object is a Null OID. If it is, CFIDRTRUE is returned. 
Otherwise, CFIDR_FALSE is returned. 

PARAMETERS 

object (input) The OID being compared to the Null OID. 

error (output) A pointer to the error relumed if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
object is not a usable OID. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

Object must be usable or the Null OID. 
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REFERENCE 

cfidrObjectlsUsableO 
cfidrPIGetNullIdO 



5.8.7 cfidrObjectlsSame 

DECLARATION 

cfidrBooleanT cfidrObjectIsSame( 
cfidrObjectldT objectl, 
cfidiObjectldT object2, 
cfidrErrorT *error) 

DESCRIPTION 

This function determines whether the OIDs specified via objectl and object2 refer to the same object. 

NOTE: This is the only mechanism which should be used to determine whether two OIDs refer to the 
same object since OIDs must be treated as abstract data types. The equality operator, should not be 
used to test for OID equality because that may not correspond to objects being the same. 

RETURN VALUE 

The return value denotes whether or not the objects passed in refer to the same object. If they do 
CFIDR_TRUE is returned. Otherwise, CFIDR_FALSE is returned. 

PARAMETERS 

objectl (input) The OID of the first object being compared. 
object2 (input) The OID of the second object being compared. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDRJUNUSABLE_OID: 

either objectl or object2 is not a usable OID. 

CFIDRJNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 
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The OIDs passed as input arguments should refer to usable objects or be the Null OID. 



5.8.8 cfidrObjectlsUsable 

DECLARATION 

cfidrBooleanT cfidrObjectIsUsable( 
cfidrObjectldT object, 
cfidrErrorT *error) 

DESCRIPTION 

This function determines whether the OID specified by object references a usable object. 

NOTE: This is the only mechanism which should be used to determine whether an OID references a 
usable object Since an OID is an abstract data type, the application can assume nothing about whether it 
represents a usable object. 

RETURN VALUE 

The return value denotes whether the object is usable or not If it is, then CFIDR_TRUE is returned 
Otherwise, CFIDRJFALSE is returned. 

PARAMETERS 

object (input) The OID of the object being checked for usability. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDK_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDILNO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

The Null OID is not usable. 

cfidrLibPurgeO and cfidrViewPurgeO cause objects to become unusable. 
REFERENCE 

cfidrObjectDestroyO 

cfidrLibPurgeO 

cfidrViewPurge 
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5.9 PI Environment Functions 



5.9.1 cfidrPICreateLib 

DECLARATION 

cfidrLibldT cfidrPICreateLib( 
cfidrStringT name, 
cfidrErrorT *error) 

DESCRIPTION 

This function creates a Lib (library) object that is referred to by name. 
RETURN VALUE 

The return value is a cfidrLibldT which refers to the Lib object just created. If an error occurs, a Null 
OID is returned. 

PARAMETERS 

name (input) The string representing the name of the Lib to be created. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 
CFIDRJNVALID_JNAME: 

the name parameter is not a valid string or is not a legal name. 

CFIDR^OBJECT ^ALREADY ^EXISTS: 
a Lib with the same name already exists. 

CFIDRJMTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDRJNOJERROR: 
no error occurred. 

PRE-CONDITIONS 

The system implementing the DR-PI is responsible for knowing about all libraries created and saved in 
previous sessions or created in the current session when determining whether the Lib already exists. The 
Lib need not be opened to be considered as existing. 

Each system implementing the DR-PI is responsible for creating and maintaining where the Lib's data is 
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stored. The application using the PI need not have any prior knowledge as to where the data physically 
resides. 

The name argument must conform to the character set rules for name strings. 

If cfidrPIInitO has not been called before, this function will call it before proceeding. 

POST-CONDITIONS 

A created Lib is not persistent across session boundaries until it is saved. 
REFERENCE 

cfidrPIInitO 
cfidrLibSaveO 

5.9.2 cfidrPIFindLibByName 

DECLARATION 

cfidrLibldT cfidrPIFindLibByName( 
cfidrStringT name, 
cfidrErrorT *emor) 

DESCRIPTION 

This function returns the Lib with the specified name. 
RETURN VALUE 

The return value is a cfidrLibldT referring to the Lib just found. If an error occurs, a Null OID is 
returned. 

PARAMETERS 

name (input) The name of the Lib. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
memory for this parameter. 

ERROR CODES 
CFIDRJNVALIELNAME: 

the name parameter is not a valid string or is not a legal name. 

CFIDR_OBJECT_NOTJOUND: 
no Lib with the specified name exists. 

CFIDR_INTERNAL_SYSTEMJERROR: 
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some other error occurred. 

CFIDRJ^O_ERROR: 
no error occurred. 

POST-CONDITIONS 

If the Lib was not opened prior to this function call, it is opened automatically, with mode 
CFIDRJIEAD. 

5.9.3 cfidrPIGetErrorText 

DECLARATION 

cfidrStringT cfidrPIGetErrorText( 
cfidrErrorT errorCode, 
cfidrErroiT *error) 

DESCRIPTION 

This function returns a pre-defined string describing the nature of the error specified by errorCode. All 
errors returned by PI functions defined in this document will have a pre-defined string. 

RETURN VALUE 

The value returned by the function is a cfidrStringT containing the pre-defined text In the case of an 
error the null string ("") is returned. 

PARAMETERS 

errorCode (input) The error code for which a textual description is desired. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_JNVALIDJERROR_CODE: 
errorCode is not in the range of valid error codes. 

CFIDR_JNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

POSTCONDITIONS 

The memory for the string is managed by the DR-PI. The string's value remains valid until the next 
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5.9.4 cfidrPIGetLibs 

DECLARATION 

cfidrLibsWT cfidrPIGetLibs( 
cfidrErrorT *error) 

DESCRIPTION 

This function initiates a traversal of all the Libraries known by the DR-PI (i.e., no object currently 
denned has a Life relationship defined for it). 

RETURN VALUE 

The return value is a cfidrLibsWT referring to an Iterator ID that iterates over Libraries. 

If an error occurs in cfidrPIGetLibsO, the error output argument is set and a valid Iterator ID is returned. 
In this case, calling the cfidrlterNextLibO function returns the Null OID. 

PARAMETERS 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_INTERNAL_SYSTEM JERROR: 
a system error occurred. 

CFIDRJNO _ERROR: 
no error occurred. 

POST-CONDITIONS 

The cfidrlterNextLibO function returns the OID of the next Lib known by the DR-PI. 

If no Libraries are known by the PI, an error is not returned but the first call to cfidrlterNextLibO 
returns the Null OID. 

If cfidrPIInitO has not been called before, this function will call it before proceeding. 
REFERENCE 

cfidrlterNextLibO 
cfidrPIInitO 
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5.9.5 cfidrPIGetNuUId 

DECLARATION 

cfidrObjectldT cfidrPIGetNullId( 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the definition of a Null OID. 
RETURN VALUE 

The value returned by this function is a cfidrObjectldT which is the representation of a Null OID for the 
system implementing the DR-PI. If an error occurs, the return value is undefined and the error return 
parameter should be set to an appropriate error code. 

PARAMETERS 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_JNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

POST-CONDITIONS 

If cfidrPDnitO has not been called before, mis function will call it before proceeding. 
REFERENCE 

cfidrPIInitO 

5.9.6 cfidrPHnit 

DECLARATION 

cfidrVoidTcfidrPIInit( 
cfidrErrorT *error) 

DESCRIPTION 

This function initializes the programming interface. Calling most other DR-PI functions before calling 
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this function will result in an error (at least for those functions accepting or returning OIDs). 
PARAMETERS 

error (output) A pointer to the eiror returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDRJNTERNAL_SYSTEMJERROR: 
some other error occurred. 

CFIDR_NOJERROR: 
no error occurred. 

PRE-CONDITIONS 

All object IDs are invalid before calling this function for the first time. However, the functions 
cfidrPIFindLibByNameO, cfidrPICreateLibO, cfidrPIOpenViewO, and cfidrPIOpenSelectorSetO are 
called with strings, and the functions cfidrPIGetLibsO, cfidrPIGetSelectorSetsO, cfidrPIQuitO, and 
cfidrPIGetNulIIdO have no OID parameters, so all of these functions will automatically call cfidrPIInitO 
if it has not been done before. 

POST-CONDITIONS 

All OIDs created after calling this function remain usable until the object (or its owner) is destroyed 
using cfidrObjectDestroyO, is purged using cfidrLibPurgeO, cfidrViewPurgeO, cfidrSelectorSetPurgeO 
or a call to cfidrPIQuitO is made. 

There are no side effects if the function is called multiple times without an ending cfidrPIQuitO- 
REFERENCE 

cfidrObjectDestroyO 

cfidrObjectPurgeO 

cfidrPIQuitO 

cfidrPICreateLibO 

cfidrPIOpenLibO 

cfidrPIOpenViewO 

cfidrPIGetLibsO 

CfidrPIGetNulIIdO 



5.9.7 cfidrPIOpenLib 

DECLARATION 

cfidrLibldT cfidrPIOpenLib( 
cfidrStringT name, 
cfidrAccessModeT mode, 
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cfidrEirorT *error) 
DESCRIPTION 

This function opens up a Lib (library) specified via name. Mode can be CFIDR_READ or 
CFE>R_UPDATE. A Lib must be opened for update for Cells, Views, and Properties to be added to or 
deleted from the Lib. This function can be used for upgrading a Lib originally opened for 
CFIDRJREAD (possibly via an implicit open) to CFIDR_UPDATE. 

RETURN VALUE 

The return value is a cfidrLibldT referring to the Lib just opened. If an error occurs, a Null OID is 
returned. 

PARAMETERS 

name (input) A string representing the name of the Lib to be opened. 

mode (input) The mode to open the Lib - CFIDR_READ for read-only access, CFEDRJUPDATE to 
allow modification. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 
CFIDR_INVALID_NAME: 

the name parameter is not a valid string or is not a legal name. 

CFIDRJLIB_ALREADY_OPEN: 

a Lib with the specified name is already open. 

CFIDR_OBJECT_NOT_FOUND: 
no Lib with the specified name exists. 

CFIDR_LIB_OPEN RAILED: 

a Lib with the specified name cannot be opened for some reason. For instance, the user may have no 
access rights. 

If the request is for CFIDRJtEAD, this error means mat either the user has no read access rights. 

If the request is for CFIDRJJPDATE, this error means that either the user has no write access rights. 

CFIDR_INVALID^\CCESSMODE: 

mode is outside of the range of legal access mode values. 

CFIDRJNTERNAL_SYSTEMJERROR: 
some other error occurred. 

CFIDR_NOJERROR: 
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no error occurred. 
PRE-CONDITIONS 

If the Lib had been created and saved in a previous session, then it is by definition available to be 
opened in the current session. 

If the Lib does not exist, it is not created automatically. 
POST-CONDITIONS 

Opening a Lib means the object hierarchy owned by the Lib is made available until Views are 
encountered. Views are opened independently via cfidrPIOpenViewO or by traversing the iterator 
returned for a Cell's Views attribute (cfidrCeUGetViewsO) using the cfidrlterNextViewO function. 

If the Lib has been previously opened but not purged in the current session, then opening it again returns 
the same OID. In this case, the error output argument should be set to CFIDR_LIB_ALREADY OPEN 
to denote this fact even though it is not an error. 

If the library was already open with CFIDR_READ but the mode is now CFIDRJJPDATE, the chances 
will now be allowed. 

If the library was already open with CFIDRJUPDATE but the mode is now CFIDR_READ, then no 
turther changes will be allowed, but any prior changes (made after the open for update but before the re- 
open for read-only) will be made persistent if a cfidrLibSave 0 is done. 

If cfidrPIInitO has not been called before, this function will call it before proceeding. 

REFERENCE 

cfidrCeUGetViewsO 
cfidrPIOpenViewO 
cfidrlterNextViewO 
cfidrPIInitO 



5.9.8 cfidrPIOpenView 

DECLARATION 

cfidrViewIdT cfidrPIOpenView( 
cfidrStringT libName, 
cfidrStringT cellName, 
cfidrStringT viewName, 
cfidrAccessModeT mode, 
cfidrErrorT *error) 

DESCRIPTION 

This function opens the View specified by libName, cellName, and viewName. Mode can be 
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CFIDRJtEAD or CFIDRJJPDATE. A View must be opened for update for objects to be added. This 
tunction can be used for upgrading a View originally opened for CFIDRJtEAD (possibly via an 
implicit open) to CFIDRJJPDATE. ^ y 

RETURN VALUE 

JfilS?. Vdue iS 8 cfidrViewIdT referrin g to the View just or already opened. If an error occurs, a 
Null OID is returned. " 

PARAMETERS 

UbName (input) A string representing the name of the Lib in which the View is supposed to exist 
cellName (input) A string representing the name of the Cell in which the View is supposed to exist. 
viewName (input) A string representing the name of the View to be opened. 

mode (input) The mode to open the View - CFIDR_READ for read-only access, CFIDR UPDATE to 
allow modification. ~ 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 
CFIDR_INVALID_NAME: 

one or more of the libName cellName viewName parameters is not a valid string or is not a legal name. 
CFIDR_VIEW_ALREADY_OPEN: 

a View with the specified libName cellName viewName is already open. 
CFIDR_OBJECT_NOT_ J FOUND: 

no View with the specified libName cellName viewName exists. 
CFIDR_VIEW_OPEN_F AILED: 

a View with the specified name cannot be opened for some reason. For instance, me user may have no 
access rights. 

If the request is for CFIDRJtEAD, this error means that either the user has no read access rights. 

If the request is for CFIDRJJPDATE, this error means that either the user has no write access rights. 

CFIDRJNVALID^ACCESSMODE: 

mode is outside of the range of legal access mode values. 

CFIDRJNTERNAL_SYSTEMJiRROR: 
some other error occurred. 

CFIDRJsJOJiRROR: 
no error occurred. 
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PRE-CONDITIONS 

The View is not created automatically if it does not exist already. See 

cfidrCellCreateEncapsolatedViewO and cfidrCellCreateNetlistViewO for details on how to create 
new views. 

POST-CONDITIONS 

Opening a NetlistView means the object hierarchy owned by the NetlistView is made available. 

Opening an EncapsulatedView means that its ViewType and Key attributes are now available. An 
implemented of this function may optionally also open the encapsulated information referenced by the 
EncapsulatedView—if that is meaningful. However, this is not required since the particulars of 
encapsulated information are, by definition, system dependent 

If the View has been previously opened but not purged in the current session, then opening it again 
returns the same OID. In this case, the error output argument should be set to 
CFIDR_VIEW_ALREADY_OPEN to denote this fact even though it is not an error. 

If the Lib owning the Cell and View has not been opened already, it will be opened with the same Mode 
parameter. If that Lib open fails, the error return from this function will be the same as the error return 
from a call to cfidrPIOpenLibO had been called with that Mode. If the View open fails, the open status 
of the Lib is indeterminate. 

If the View was already open with CFIDR_READ but the mode is now CFIDRJUPDATE, then changes 
will now be allowed. ' 

If the View was already open with CFIDRJUPDATE but the mode is now CFID REREAD, then no 
further changes will be allowed, but any prior changes (made after the open for update but before the re- 
open for read-only) will be made persistent if a cfidrLibSaveO or cfidrViewSaveO is done. 

If cfidrPIInitO has not been called before, this function will call it before proceeding. 

Opening a particular NetlistView has two non-obvious side effects: 

(1) if an Inst has that NetlistView in its Describer attribute, it will not be necessary to automatically 
open that NetlistView when accessing Describer, 

(2) for any Inst whose Owner attribute is that particular NetlistView, it will be possible to access the 
Describer attribute without an (automatic) open if the NetlistView in Describer is open already. 

REFERENCE 

cfidrPIInitO 
cfidrPIOpenLibO 

cfidrCellCreateEncapsulatedViewO 
cfidrCellCreateNeUistViewO 



5.9.9 cfidrPIQuit 
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DECLARATION 

cfidrVoidTcfidrPIQuit( 
cfidrErrorT *enor) 

DESCRIPTION 

This function terminates the execution of the programming interface. Calling any other DR-PI function 
after calling this function will normally result in an error (at least for those functions accepting or 
returning OIDs). 

PARAMETERS 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

cfidrPIQuitO may have already been called. This is not an error. 
POST-CONDITIONS 

All OIDs created since calling cfidrPIInitO are made unusable after calling this function. Subsequently 
calling cfidrPIInitO starts another session boundary and does not subsequently make usable any OIDs 
defined prior to the call to cfidrPIQuitO- 

Quitting the DR-PI does not automatically save any information. The application must call 
cfidrLibSaveO or cfidrViewSaveO in order to update the persistent data. 

REFERENCE 

cfidrPIInitO 

cfidrLibSaveO 

cfidrViewSaveO 
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5.10 Port Functions 



5.10.1 cfidrPortGetOwner 

DECLARATION 

cfidrObjectldT cfidrPortGetOwner( 

cfidrPortldTport, 

cfidrErrorT *error) 

DESCRIPTION 

This function returns the object (View or PortBundle) at the end of the Owner relationship for the Port 
specified by port. 

RETURN VALUE 

The return value is a cfidrObjectldT referring to the View or PortBundle at the end of the Owner 
relationship. If an error occurs, a Null OID is returned. 

PARAMETERS 

port (input) The OID of the Port whose Owner relationship is to be followed. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
port is not a usable OID. 

CTIDRJttiVALlDjOBJECTTYPE: 
port is not the OID of a Port 

CFIDR_INTERNAL_SYSTEM _ERROR: 
some other error occurred. 

CFff>R_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

The Owner relationship is defined when an object is created but can be modified later by the 
cfidrPortSetOwnerViewO and cfidrPortSetOwnerPortBundleO functions. 
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POST-CONDITIONS 

Use the cfidrObjectGetObjectTypeO function to determine the Owner's object type. 

REFERENCE 

cfidrObjectGetObjectTypeO 

cfidrPortSetOwnerPortBundleO 

cfidrPortSetOwnerViewO 

5.10.2 cfidrPortGetPosition 

cfidrInt32T cfidrPortGetPosition( 
cfidrPortldT port, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the position of the specified port in its owner. 

RETURN VALUE 
The return value is a cfidrInt32T. If an error occurs, a -1 is returned. 

PARAMETERS 
port (input) The OID of a Port. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
port is not a usable OID. 

CTroRjNVALIDjOBJECTTYPE: 
port is not the OID of a Port. 

CFIDR w INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NQJBRROR: 
no error occurred. 

PRE-CONDITIONS 

The owner of the Port may be either the View or a PortBundle (or PortBus). 
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POST-CONDITIONS 

The returned position will be 0 for the first Port in the owner up to size-1 for the last position, where size 
is the number of ports in the list of ports owned by port's owner. 

REFERENCE 

cfidrPortSetOwnerPortBundleO 

cfidrPortBundleCreatePortBundleO 

cfidrNetlistViewCreatePortBundleO 



5.10.3 cfidrPortSetOwnerPortBundle 

DECLARATION 

cfidrVoidT cfidrPortSetOwnerPortBundle( 
cfidrPortldTport, 
cfidrPortBundleldT owner, 
cfidrInt32T position, 
cfidrErrorT *error) 

DESCRIPTION 

This function changes the Owner of the specified Port to the PortBundle specified by owner and inserts 
it at the specified position. The port is removed from its previous parent (either PortBundle or View) in 
the process. 

PARAMETERS 

port (input) The OID of the Port whose owner is to be changed. 

owner (input) The OID of the new owning PortBundle. 

position (input) The desired location of the port within its new owner PortBundle. If position is less than 
0 or greater than or equal to the number of members in the list of Ports owned by owner, the new Port is 
appended as the last member of the list. Otherwise, it is inserted at the specified position in the list (0 is 
the first member). 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
memory for this parameter. 

ERROR CODES 

CFIDRJJNUSABLE_OID: 
port is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
port is not the ODD of a Port. 
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CFIDR_UNUSABLEJ>ORTBUNDmj3ID: 
owner is not a usable OID. 

CFIDR__INVALID _J > ORTBUNDLE_JTYPE: 
owner is not the OID of a PortBundle 

CFmRJsIAMEJNJJSE: 

the name of the Port matches the name of a Port already owned by the PortBundle. 

NOTE: This code is not returned when only the position is being changed but not the owner. 

CFIDR_CROSS_VIEW_OPERATION: 

the owner PortBundle and the port member belong to different Views. 

CFIDR_MEMBERJRECURSION: 

the owner and port OIDs refer to the same object. 

CFI_READ_ONLY: 

the containing View has not been opened for update. 

CFIDRJNTERNAL_SYSTEMJERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

Both the Port and PortBundle must belong to the same parent View. 

The name of the Port must be unique with respect to all other Ports owned by the owner PortBundle. 
It is not permitted to add a Port as a member of itself. 

The port may already be a member of the specified owner PortBundle, In this case only the position is 
changed (if it is different from the previous Position). Do not return the code CFIDR_NAME_IN_USE 
in this case. 

POST-CONDITIONS 

If port is already a member of a PortBundle, it will be removed from the list of members of its current 
owner. All remaining members of that list will be moved down one position. 

If port is a member of a NetlistView, it will be removed from the list of members of that NetlistView. 
All remaining members of that list will be moved down one position. 

The Port is added to the list of Ports owned by owner at position. If position = 0, the new Port will be 
added as the first member of the list If position is less than 0 or greater than or equal to the number of 
members in the list, the new Port is appended to the end of the list. Otherwise, the Port is inserted at the 
specified position (0 based). The position of all members whose positions were greater than or equal to 



http://www.si2.org/si2 jublications/htmlSpecs/DR/part5b.fin4.html 



6/23/2004 



Page 5 of 76 



position, will have their position incremented by 1. 

For example, presume a View has Port members: 
View Ports = {A, B, CO, 1,2} 

and PortBundle B has members: 
B's Port members = {bl, b2, b3} 

Setting the owner of Port CO to position 1 of B results in: 

View ports = {A, B, 1,2} 

B f s port members = {bl, CO, b2, b3}. 

Position specifies the position of the Port * AFTER* the function executes, even in the case where 
Owner specifies the current owner of Port. 

If the Port is connected to a Net, then an implicit detach of the parent bundles will result if that was the 
last such connection, and an implicit attach of the new parent bundles will result if it is the first such 
connection. 

See the discussion, ^N^imdje Cpim^^ 
for additional implications. 

REFERENCE 

cfidrPortSetOwnerViewO 
cfidrPortBundleGetPortsO 
cfidrPortBundleCreatePortBundleO 
cfidrNetlistViewCreatePortBundleO 



5.10.4 cfidrPortSetOwnerView 

DECLARATION 

cfidrVoidT cfidrPortSetOwnerView( 
cfidrPortldTport, 
cfidrInt32T position, 
cfidrErrorT *error) 

DESCRIPTION 

This function changes the Owner of a Port owned by a PortBundle to the NetlistView which was its 
ultimate, indirect owner. If the Port is already owned by a NetlistView the Owner is not changed. The 
Port specified by port is then moved (if necessary) such that its final position in the Ports of the 
NetlistView is position. 

PARAMETERS 

port (input) The OID of the Port whose Owner is to be changed. 
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position (input) The desired location of the port within the NetlistView. If position is less than 0 or 
greater than or equal to the number of members in the list of Ports owned by owner, the new Port is 
appended as the last member of the list. Otherwise, it is inserted at the specified position in the list (0 is 
the first member). 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
memory for this parameter. 

ERROR CODES 

CFIDRJJNUSABLE_OID: 
port is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 

port is not the OID of a Port (PortBundle, PortBus, or PortScalar). 
CFIDRJ*AMEJN_USE: 

the name of the Port matches the name of a Port already owned by the NetlistView. 
CFIDRJtEADONLY: 

the containing View has not been opened for update. 

CFIDRJNTERNALJSYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

If the Port is owned by a PortBundle, the name of the Port must be unique with respect to all other Ports 
owned by the NetlistView which is the ultimate owner of the PortBundle. 

The Port may be owned by a NetlistView. In this case only the Position will be changed (if the specified 
position is different than the current Position). Do not return the code CFIDRJMAMEJNJJSE in this 
case. 

POST-CONDITIONS 

If port is owned by a PortBundle, it is removed from that PortBundle. 

If port is owned by a PortBundle the ultimate owning NetlistView is determined by getting the Owner of 
the PortBundle. If Owner is a PortBundle then Owner of that PortBundle is obtained. This is repeated 
until an Owner of type NetlistView is returned. 

The positions of all Ports within its previous Owner that are greater than or equal to the port's original 
Position will be decremented by one. 

The Port is then inserted in the list of Ports of the NetlistView at position. If position = 0, the new Port 
will be added as the first member of the list If position is less than 0 or greater than or equal to the 
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number of members in the list, the new Port is appended to the end of the list Otherwise, the Port is 
inserted at the specified position (0 based). The position of all members whose positions were greater 
than or equal to position, will have their position incremented by 1 . 

For example, presume a View has Port members: 
View Ports = {A, B, CO, 1, 2} 

and PortBundle B has members: 
B's Port members = {bl , b2, b3 } 

Setting the owner of Port b2 to position -1 of the NetlistView results in: 
View ports = {A, B, CO, 1, 2, b2} 
B's port members = {bl, b3) . 

Position specifies the position of the Port * AFTER* the function executes, even in the case where 
Owner specifies the current owner of Port. 

If the Port is connected to a Net, then an implicit detach of the parent bundles will result if that was the 
last such connection. 

See the discussion, "NetBundle Connection to PortflnstlBundle is a Derived Relationship^^nj).age4r35, 
for additional implications. 

REFERENCE 

cfidrPortSetOwnerPortBundleO 
cfidrPortBundleGetPortsO 
cfidrPortBundleCreatePortBundleO 
cfidrNeUistViewCreatePortBundleO 

5.10.5 cfidrPortBundleCreatePortBundle 

DECLARATION 

cfidrPortBundleldT cfidrPortBundleCreatePortBundle( 
cfidiPortBundleldT owner, 
cfidrStringT name, 
cfidrInt32T position, 
cfidrErrorT *error) 

DESCRIPTION 

This function creates a PortBundle object owned by the PortBundle specified via owner. 
RETURN VALUE 

The return value is a cfidrPortBundleldT referring to the PortBundle object just created. If an error 
occurs, a Null OID is returned. 
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PARAMETERS 



owner (input) The OID of the PortBundle owning the PortBundle being created. 

name (input) The string representing the name of the PortBundle being created. 

position (input) The integer specifying the position of the PortBundle in the list of Ports owned by 
owner. A position value less than 0 or greater than or equal to the number of ports indicates the new 
PortBundle is put at end of the list. Any other value, including 0, indicates the actual position in the list. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 



CFIDRJJNUSABLE_OID: 
owner is not a usable OID. 

CFIDR_INVAL1D_0BJECTTYPE: 
owner is not the OID of a PortBundle. 



CFIDR__READ_ONLY: 

the containing View has not been opened for update. 
CFIDR_INVALID_NAME: 

the name parameter is not a valid string or is not a legal name. 
CFIDR_NAME_JN_USE: 

the name parameter specifies a name already in use in the same name scope but not for a PortBundle. 

CFIDR_OB JECT_ALREAD Y_EXISTS : 

a PortBundle with the same name already exists for this owner. 

CFIDR_JNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 



PRE-CONDITIONS 



The name argument must conform to the character set rules for name strings. 

A Port named name that is owned by the same PortBundle as specified by owner cannot already exist. 

POST-CONDITIONS 



The PortBundle is created with no members initially. Later, Ports or PortBundles may either be created 
in or have their owner changed to be this PortBundle. Furthermore, this PortBundle may later have its 
owner changed to the View or to another PortBundle. 
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The PortBundle is created and added to the list of Ports owned by the PortBundle specified by owner at 
the position specified by position. If position = 0, the new PortBundle will be added as the first member 
of the list If position is less than 0 or greater than or equal to the number of members in the list, the new 
PortBundle is appended to the end of the list Otherwise, the PortBundle is inserted at the specified 
position (0 based). The position of all Ports whose positions were greater than or equal to position, will 
have their position incremented by 1 . For example, presume the owner initially has Ports- 
A, B, CO, 1,2. 

Adding a new member X at position 1 results in: 
A,X,B,C0, 1,2 

Note that B had position 1 before and has position 2 after X is created. 

Adding X at position 0 causes X to be at the beginning of the list: 
X, A, B, CO, 1, 2 

Adding X at an invalid position such as -1 (or any value greater than 4) causes creation of the new 

member at the end of the list: 

A,B,C0,1,2,X 

REFERENCE 

cfidrPortBundleGetOwnerO 

cfidrPortBundleGetPortsO 

cfidrPortSetOwnerPortBundleO 

cfidrPortSetOwnerViewO 

cfidrNetlistViewCreatePortBundleO 

cfidrNethstViewCreatePortScalarO 

cfidrNetlistViewGetPortsQ 



5.10.6 cfidrPortBundleCreatePortBus 

DECLARATION 

cfidrPortBusIdT cfidrPortBundleCreatePortBus( 

cfidrPortBundleldT owner, 

cfidrStringT name, 

cfidrInt32T position, 

cfidrInt32T start 

cfidrInt32T step 

cfidrErrorT *error) 

DESCRIPTION 

This function creates a PortBus object located at the position position in the list of Ports owned by the 
PortBundle specified via owner. The PortBus Name attribute is set to name. The PortBus Start attribute 
is set to start. The PortBus Step attribute is set to step. 

RETURN VALUE 
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The return value is a cfidrPortBusIdT referring to the PortBus object just created. If an error occurs, a 
Null OID is returned. 

PARAMETERS 

owner (input) The OID of the PortBundle owning the PortBus being created. 
name (input) The string representing the name of the PortBus being created. 

position (input) The integer specifying the position of the PortBus in the list of Ports owned by owner. A 
position value less than 0 or greater than or equal to the number of ports indicates the new PortBus is put 
at end of the list. Any other value, including 0, indicates the actual position in the list. 

start (input) The Int32 defining the index of position 0 in the bus. 

step (input) The Int32 defining the difference in indexes of positions n and n+1 in the bus. This number 
must be non-zero. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
owner is not a usable OID. 

CFlDR_INVALID_OBJECTTYPE: 
owner is not the OID of a PortBundle. 

CFIDR_READ_ONLY: 

the containing View has not been opened for update. 
CFIDR_JNVALID_NAME: 

the name parameter is not a valid string or is not a legal name. 
CFIDR_NAME_IN_USE: 

the name parameter specifies a name already in use in the same name scope but not for a PortBus. 

CFIDR_OBJECT_ALREADY_EXISTS: 
a PortBus with the same name already exists. 

CFIDR_INVALID_VALUE 
Step is 0. 

CFIDR_INTERNAL_SYSTEM JERROR: 
some other error occurred. 

CFIDRJsJOJERROR: 
no error occurred. 
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PRE-CONDITIONS 

The name argument must conform to the character set rules for name strings. 

A Port (PortScalar, PortBundle, or PortBus) with the given name cannot already exist in the PortBundle 
specified by owner. 

POST-CONDITIONS 

The newly created PortBus will initially have no members and a size of 0. 

The PortBus created by this function can later be changed to have a different PortBundle as its owner 
using the cfidrPortSetOwnerPortBundleO function or to have a View as its owner using the 
CfidrPortBundleSetOwnerViewO function. 

The Start and Step attributes may be changed later by use of the cfidrPortBusSetStartO and 
cfidrPortBusSetStepO functions. 

REFERENCE 

cfidrPortBundleGetSizeO 

cfidrPortBundleGetNetsO 

cfidrPortBundleGetPortsO 

CfidrPortBundleSetOwnerViewO 

cfidrPortBusGetStartO 

cfidrPortBusGetStepO 

cfidrPortBusSetStartO 

cfidrPortBusSetStepO 

CfidrPortSetOwnerPortBundleO 

cfidrNetlistViewGetPortsO 



5.10.7 cfidrPortBundleCreatePortScalar 

DECLARATION 

cfidrPortScalarldT cfidrPortBundleCreatePortScalar( 

cfidrPortBundleldT owner, 

cfidrStringTname, 

cfidrInt32T position, 

cfidrPortDirectionT direction, 

cfidrErrorT *error) 

DESCRIPTION 

This function creates a PortScalar object owned by the PortBundle specified via owner and located at 
position in the list of Ports owned by owner. The PortScalar name attribute is set to name. The 
PortScalar direction attribute is set to direction. 

RATIONALE 
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The PortScalar is created with all required attributes set including the derived attribute of position. 
RETURN VALUE 

The return value is a cfidrPortScalarldT referring to the PortScalar just created. If an error occurs a Null 
OID is returned. 

PARAMETERS 

owner (input) The OID of the PortBundle owning the PortScalar to be created. 
name (input) The string representing the name of the PortScalar. 

position (input) The integer specifying the position of the PortScalar in the list of Ports owned by owner. 
A position value less than 0 or greater than or equal to the number of ports indicates the new Port is put 
at end of the list. Any other value, including 0, indicates the actual position in the list. 

direction (input) The Direction attribute to assign to the created PortScalar. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CTroRJJNUSABLEJDE): 
owner is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
owner is not the OID of a PortBundle. 

CFIDRJREADjONLY: 

the containing View has not been opened for update. 
CFIDR_INVALIDJ*AME: 

the name parameter is not a valid string or is not a legal name. 
CFIDR_NAMEJN_USE: 

the name parameter specifies a name already in use in the same name scope but not for a PortScalar. 

CFIDRJDBJECT_ALREADY ^EXISTS: 

a PortScalar with the same name already exists for owner. 

CFIDRJNVALIDJDIRECTION: 
direction is not a legal PortDirection. 

CFIDRJNTERNAL_SYSTEMJERROR: 
some other error occurred. 

CFIDRJNOJERROR: 
no error occurred. 
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PRE-CONDITIONS 

The name argument must conform to the character set rules for name strings. 

A Port (Scalar, Bundle, or Bus) with the given name cannot already be owned by the PortBundle 
specified by owner. However, a Port with the same name may exist indirectly in the View or in another 
PortBundle. This is allowed since the scope of Port names is the owning View or the owning 
PortBundle. 6 



POST-CONDITIONS 



The owner of the PortScalar created by this function can later be changed to the View or to a PortBundle 
provided no other Port has the same name in the new owner. 

The PortScalar is created and added to the list of Ports owned by the NetlistView specified by owner at 
the position specified by position. If position = 0, the new PortScalar will be added as the first member 
of the list If position is less than 0 or greater than or equal to the number of members in the list, the new 
PortScalar is appended to the end of the list Otherwise, the PortScalar is inserted at the specified 
position (0 based). The position of all Ports whose positions were greater than or equal to position, will 
have their position incremented by 1. For example, presume a View has Ports: 
A,B,C0,1,2. 

Adding a new member X at position 1 results in: 
A, X, B, CO, 1, 2 

Note that B had position 1 before and has position 2 after X is created. 

Adding X at position 0 causes X to be at the beginning of the list: 
X, A, B, CO, 1, 2 

Adding X at an invalid position such as -1 (or any value greater man 4) causes creation of the new 
member at the end of the list: 
A, B, CO, 1, 2, X 

REFERENCE 

cfidrPortBundleCreatePortBundleO 

cridrPortBundleCreatePortScalarO 

cfidrPortBundleGetOwnerO 

cfidrPortBundleGetPortsO 

cfidrPortSetOwnerPortBundleO 

cfidrPortSetOwnerViewO 

cfidrNetlistViewGetPortsO 



5.10.8 cfidrPortBundleFindPortByName 

DECLARATION 

cfidrPortldT cfidrPortBundleFindPortByName( 
cfidrPortBundleldT portBundle, 
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cfidrStringT name, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the Port with the specified name that is within the Ports relationship defined for the 
PortBundle specified by portBundle. 

RETURN VALUE 

The return value is a cfidrPortldT referring to the Port just found. If an error occurs, a Null OID is 
returned. 

PARAMETERS 

portBundle (input) The OID of the PortBundle from which the Port is to be found, 
name (input) The name of the Port. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
memory for this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
portBundle is not a usable OID. 

CFIDR_JNVALID_OBJECTTYPE: 
portBundle is not the OID of a PortBundle. 

CFIDR W INVALID_NAME: 

the name parameter is not a valid string or is not a legal name. 

CFIDR_OBJECT_J^OT_FOUND: 
no Port with the specified name exists. 

CFIDR_INTERNAL_SYSTEM_ERROR : 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

Only the immediate list of Ports directly owned by the specified portBundle is searched by this function. 
Thus a Port that is indirectly owned by this portBundle will not be returned by this function. 



5.10.9 cfidrPortBundleFindPortByPosition 
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cfidrPortldT cfidrPortBundleFindPortByPosition( 
cfidrPortBundleldT portBundle, 
cfidrInt32T position 
cfidrErroiT *error) 

DESCRIPTION 

This function returns the Port at the specified position within the specified portBundle. The "leftmost" or 
first position is numbered 0 and the "rightmost" or last position is numbered one less than the size of the 
bundle. 

RETURN VALUE 

The return value is a cfidrPortldT referring to the Port just found. If an error occurs, a Null OID is 
returned. 

PARAMETERS 

portBundle (input) The OID of the PortBundle being accessed. 

position (input) The position of the returned Port in the PortBundle. A value of 0 will return the Port at 
the first position. A value one less than the size of the bundle will return the Port at the last position. A 
value greater than or equal to the size of the bundle or any negative value will cause an error. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CTIDR_UNUSABLE_OID: 
portBundle is not a usable OID. 

CTIDRJNVALID^OBJECTTYPE: 
portBundle is not the OID of a PortBundle. 

CFIDRJNVALIDJPOSrnON: 

the position parameter is not in the range 0 to one less than the size of the bundle. 

NOTE: If the bundle size is 0, this code is returned since no position is valid. 

CFIDRJMTERNALJSYSTEMJERROR: 
some other error occurred. 

CFIDRJsfOJERROR: 
no error occurred. 

REFERENCE 

cfidrPortSetOwnerPortBundleO 
cfidrPortBundleCreatePortO 
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cfidrNetUstViewCreatePortBundleO 



5.10.10 cfidrPortBundleGetNetBundles 



DECLARATION 



cfidrNetBundlesIdTcfidrPortBundleGetNetBundles( 
cfidrPortBundleldT portBundle, 
cfidrErrorT *error) 

DESCRIPTION 



^^^^^^^^^^^ 



defined 
connects. 

RETURN VALUE 

The return value is a cfidrNetBimdlesIdT referring to an Iterator ID that i^^^KlfS A 
valid Iterator ID is always returned, even when an error occurs. In the case of an error, calhng the 
cfidrlterNextNetBundleO function returns a Null OID. 

PARAMETERS 

portBundle (input) The OID of a PortBundle for which the NetBundles relationship is to be traversed. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDRJUNUSABLE_OID: 
portBundle is not a usable OID. 

CFlDR_INVALID_OBJECTTYPE: 
portBundle is not the OID of a PortBundle. 

CFIDRJNTERNAL^SYSTEM3RROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

owned directly or indirectly by the PortBundle. 
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POST-CONDITIONS 

The cfidrlterNextNetBundleO function returns the next NetBundle Off) in the NetBundles 
relationship. 

If no objects are currently present in the NetBundles relationship, an error is not returned but the first 
call to cfidrlterNextNetBundleO returns a Null OID. 

REFERENCE 

cfidrlterNextNetO 
cfidrlterNextNetBundleO 



5.10.11 cfidrPortBundleGetPorts 

DECLARATION 

cfidrPortsIdT cfidrPortBundleGetPorts( 
cfidrPortBundleldT portBundle, 
cfidrlterModeT mode, 
cfidrErrorT *error) 

DESCRIPTION 

This function initiates a traversal of all of the Ports (PortBundles, PortBusses, or PortScalars) at the end 
of the Ports relationship defined for the PortBundle specified by portBundle. 

RETURN VALUE 

The return value is a cfidrPortsIdT referring to an Iterator ID that iterates over Ports. A valid Iterator ID 
is always returned, even when an error occurs. In the case of an error, calling the cfidrlterNextPortO 
function returns a Null OID. 

PARAMETERS 

portBundle (input) The OID of a PortBundle for which the Ports relationship is to be traversed. 

mode (input) The mode that determines which Ports are returned. The current valid values are 
CFIDRJTERJSCALARS, CFIDRJTER^BUNDLES, CFIDRJTERJTOP, and CFIDRJTER_ALL. 
See the Pre-Conditions below for more detail on how these modes behave. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFroiUJNUSABLE_OID: 
portBundle is not a usable OID. 
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CFIDRJNVALID_OBJECTTYPE: 
portBundle is not the OID of a PortBundle. 

CFIDR_INVALID_ITERMODE: 
mode is not a valid IterMode. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDILMO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

Ports directly in a PortBundle each have a unique Position in the list of Ports owned by the PortBundle. 
The positions in this list are numbered from 0 for the "leftmost" or first position monotonically 
increasing by 1 up to one less than the size of the list. The order in which the Ports are returned from any 
given PortBundle is by increasing position starting with 0. The Position of a given Port at a given time is 
determined by the various operations that have been performed on the list of Ports including: 

( 1 ) the position specified when a Port is created in the PortBundle, 

(2) the position specified when the Port had its Owner set to this PortBundle, 

(3) appearances and disappearances of Ports at or to the "left" of the Position of the given Port due to 
changes in those Porfs Owner. 

This function can also be used for PortBusses since they are a subtype of PortBundle. 
POST-CONDITIONS 

The returned list of Ports is accessed by using calls to cfidrlterNextPortO on the iterator returned by 
this function. Each iteration returns another Port OID that is directly or indirectly in the Ports 
relationship based on 

(1) the value of the mode parameter and 

(2) the Position of that Port in its Owner's Ports relationship and (other than for mode 
=CFIDR_ITER_TOP) any intervening levels of PortBundles. 

If no objects are currently present in the Ports relationship under the specified mode, an error is not 
returned but the first call to cfidrlterNextPortO returns a Null OID. 

The Ports that are included when iterating over the cfidrPortsIdT iterator returned from this function 
depends on the mode argument specified. 

mo<fe=CFIDRJTER_TOP 

Returns all those Ports (PortBundles, PortBusses, or PortScalars) which are directly owned by the 
PortBundle. 

moc?e=CFIDRJTER_SCALARS 

Returns the PortScalars directly owned by portBundle and recursively owned by PortBundles owned by 
portBundle. No PortBundles are output with mis mode, only PortScalars. The order is based on a depth- 
first recursion. 
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mo<fe=CFIDRjrrERJBUNDLES 

Returns all the PortBundles (including PortBusses) owned directly by portBundle and recursively by 
those PortBundles (and PortBusses). No PortScalars are output The order is determined by depth-first 
recursion. 

mode=CFIDR_ITER_ALL 

Returns all the Ports (PortBundles, PortBusses, or PortScalars) directly or indirectly owned by 
portBundle. This mode combines the PortScalars returned when mo<fe=CFIDR_ITER_SCALARS with 
the PortBundles returned when mo£fe=CFIDR_ITER_BUNDLES. 

For all values of mode except worfe=CFIDR_ITER_TOP, note that the Port Name scoping rules state 
that Port Names need only be unique within the Ports of their Owner, which is either the View or a 
PortBundle. Thus, a Port may exist in the View while others with the same name exist in different 
PortBundles. Thus, in the Ports returned via these modes, the same name may appear more than once 
even though they are different Ports and have different OIDs. The function cfidrObjectlsSameO must 
be used in this case to determine if two Ports with the same name are actually the same object. 

REFERENCE 

cfidrlterNextPortO 
cfidrObjectlsSameO 
cfidrPortSetOwnerPortBundleO 
cfidrPortSetOwnerViewO 



5.10.12 cfidrPortBundleGetSize 

DECLARATION 

cfidrInt32T cfidrPortBundleGetSize( 
cfidrPortBundleldT portBundle, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the number of Ports currently in the specified portBundle. This is only the number 
at the next level and not a count of the total number of scalars in the bundle. 

RETURN VALUE 

The return value is a cfidrInt32T. If an error occurs, a -1 is returned. 

PARAMETERS 
portBundle (input) The OID of a PortBundle. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 
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CFIDR_UNUSABLE_OID: 
portBundle is not a usable OID. 

CFIDR^INVALIDjOBJECTTYPE: 
portBundle is not the OID of a PortBundle. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDRJIO^ERROR: 
no error occurred. 

PRE-CONDITIONS 

PortBundles are created initially with Size zero. PortBundle members are created using 
cfidrPortBundleCreatePortBundleO and cfidrPortBundleCreatePortScalarO. PortBundle members 
are added and deleted via cfidrPortSetOwnerPortBundleO and cfidrPortSetOwnerViewO 

REFERENCE 

CfidrPortSetOwnerPortBundleO 

CfidrPortSetOwnerViewO 

cfidrPortBundleCreatePortBundleO 

cfidrPortBundleCreatePortScalarO 

cfidrNetlistViewCreatePortBundleO 



5.10.13 cfidrPortBusGetStart 

DECLARATION 

cfidrInt32T cfidrportBusGetStart( 
cfidrportBusIdT portBus, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the start attribute of the specified portBus. This specifies the first index value for 
this bus. 

RETURN VALUE 
The return value is a cfidrint32T. If an error occurs, a 0 is returned. 

PARAMETERS 
portBus (input) The OID of a PortBus. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 
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ERROR CODES 

CFIDRJJNUSABLE_OID: 
portBus is not a usable OID. 

CFIDR_INVALIDjOBJECTTYPE: 
portBus is not the OID of a PortBus. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDRJNOJBRROR: 
no error occurred 

PRE-CONDITIONS 

The start attribute of a PortBus is set at creation time or changed using cfidrPortBusSetStartO. 
REFERENCE 

cfidrPortBundleCreatePortBusO 

cfidrPortBusSetStartO 

cfidrNetlistViewCreatePortBusO 

5.10.14 cfidrPortBusGetStep 

DECLARATION 

cfidrInt32T cfidrPortBusGetStep( 
cfidrPortBusIdT portBus, 
cfidrErroiT *error) 

DESCRIPTION 

This function returns the step attribute of the specified portBus. This specifies the numeric increment 
between positions for the index. 

RETURN VALUE 
The return value is a cfidrInt32T. If an error occurs, a 0 is returned. 

PARAMETERS 
portBus (input) The OID of a PortBus. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 
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CFIDR_UNUSABLE_OID: 
portBus is not a usable OID. 

CFIDRJhTVALID_OBJECTTYPE: 
portBus is not the OID of a PortBus. 

CFIDRJNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR w NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

The Step attribute of a PortBus is set at creation time or changed using cfidrPortBusSetStepO- 
REFERENCE 

cfidrPortBundleCreatePortBusO 

cfidrPortBusSetStepO 

cfidrNetlistViewCreatePortBusO 



5.10.15 cfidrPortBusSetStart 

DECLARATION 

cfidrVoidT cfidrPortBusSetStart( 
cfidrPortBusWT portBus, 
cfidrInt32T start, 
cfidrErrorT *error) 

DESCRIPTION 

This function sets the start attribute of the specified portBus. This specifies the first index value for this 
bus. 

PARAMETERS 

portBus (input) The OID of a PortBus. 

start (input) The 32 bit integer number for the first (leftmost) index of the bus. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDRJJNUSABLE_OID: 
portBus is not a usable OID. 
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CFIDR_IN VALID_OB JECTTYPE : 
portBus is not the OID of a PortBus. 

CFIDR_READ_ONLY: 

the containing View has not been opened for update. 

CFIDR_INTERNAL_SYSTEKCERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

POST-CONDITIONS 

The Start attribute of the PortBus may be accessed using the function cfidrPortBusGetStartO- 
REFERENCE 

cfidrPortBundleCreatePortBusO 

CfidrPortBusGetStartO 

cfidrNetlistViewCreatePortBusO 



5.10.16 cfidrPortBusSetStep 

DECLARATION 

cfidrVoidT cfidrPortBusSetStep( 
cfidrPortBusIdT portBus, 
cfidrInt32T step, 
cfidrErrorT *error) 

DESCRIPTION 

This function sets the step attribute of the specified portBus. This specifies the numeric increment 
between positions for the index. 

PARAMETERS 

portBus (input) The OID of a PortBus. 

step (input) The 32 bit integer number for the step. This number must be non-zero. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
portBus is not a usable OID. 
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CFIDR^INVALIDjOBJECTTYPE: 
portBus is not the OID of a PortBus. 

CFIDR_INVALID_VALUE: 
step is zero. 

CFIDRJIEAELONLY: 

the containing View has not been opened for update. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

POST-CONDITIONS 

The Step attribute of the PortBus may be accessed using the function cfidrPortBusGetStepO 

REFERENCE 

cfidrPortBundleCreatePortBusO 

CfidrPortBusGetStepO 

cfidrNetlistViewCreatePortBusO 



5.10.17 cfidrPortScalarGetDirection 

DECLARATION 

cfidrPortDirectionT cfidrPortScalarGetDirection( 
cfidrPortScalarldT portScalar, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the Direction attribute of the PortScalar specified by portScalar. 
RETURN VALUE 

The return value is a cfidrPortDirectionT enumerated type representing the value of the Direction 
attribute. 

On error the function returns CFIDR_UNDEFINED JPORTDIRECTION. 
PARAMETERS 

portScalar (input) The OID of the PortScalar whose Direction attribute is desired. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
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the memory used by this parameter. 
ERROR CODES 

CFIDR_UNUSABLE_OID: 
portScalar is not a usable OID. 

CFIDR_INVALID_OBJEGTTYPE: 
portScalar is not the OID of a PortScalar. 

CFIDRJNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR^NOJERROR: 
no error occurred. 



5.10.18 cfidrPortScalarGetNetScalar 

DECLARATION 

cfidrNetScalarldT cfidrPortScalarGetNetScalar( 
cfidrPortScalarldT portScalar, 
cfidrErrorT *error) 

DESCRIPTION 

This function retrieves the NetScalar at the end of the NetScalar relationship defined for the PortScalar 
specified by portScalar. 

RETURN VALUE 

The return value is a cfidrNetScalarldT referring to the NetScalar at the end of the NetScalar 
relationship. If an error occurs or if there is no NetScalar attached to this PortScalar, a Null OID is 
returned. 

PARAMETERS 

portScalar (input) The OID of the PortScalar containing the NetScalar relationship which is being 
traversed. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
portScalar is not a usable OID. 

CFIDR_JNVALID_OBJECTTYPE: 
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portScalar is not the OID of a PortScalar 

CFIDRJNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDRJsTOJRROR: 
no error occurred. 

REFERENCE 
cfidrNetGetPortsQ 



5,11 Portlnst Functions 



5.11.1 cfidrPortlnstBundleFindPortlnstByDescriberName 

DECLARATION 

cfidrPortlnstldT 

cfidrPortInstBundleFindPortInstByDescriberName( 
cfidrPortlnstBundleldT portlnstBundle, 
cfidrStringT describerName, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the Portlnst with the specified describerName that is within the Portlnsts 
relationship defined for the PortlnstBundle specified by portlnstBundle. 

RETURN VALUE 

The return value is a cfidrPortlnstldT referring to the Portlnst just found. If an error occurs, a Null OID 
is returned. 

PARAMETERS 

portlnstBundle (input) The OID of the PortlnstBundle from which the Portlnst is to be found. 
describerName (input) The DescriberName of the Portlnst 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating memory for 
this parameter. 

ERROR CODES 

CTIDRJJNUSABLE_OID: 
portlnstBundle is not a usable OID. 
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CFIDRJ^ALm^OBJECTTYPE: 
portlnstBundle is not the OID of a PortlnstBundle. 

CFIDR_INVALID_NAME: 

the describerName parameter is not a valid string or is not a legal name. 

CFIDR^OBJECT^NOX-FOUND: 

no Portlnst with the specified describerName exists. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFroiOJOJERROR: 
no error occurred. 

PRE-CONDITIONS 

Only the immediate list of Portlnsts directly owned by the specified portlnstBundle is searched by this 
function. Thus a Portlnst that is only indirectly owned by this portlnstBundle will not be returned by this 
function 



5.11.2 cfidrPortlnstBundleGetNetBundles 

DECLARATION 

cfidrNetBundlesIdTcfidrPortInstBundleGetNetBundles( 
cfidrPortlnstBiindleldT portlnstBundle, 
cfidrErrorT *error) 

DESCRIPTION 

This function initiates a traversal of all of the NetBundles at the end of the NetBundles relationship 
defined for die PortlnstBundle specified by portlnstBundle. These are the NetBundles to which this 
PortlnstBundle connects. 

RETURN VALUE 

The return value is a cfidrNetBundlesIdT referring to an Iterator ID that iterates over NetBundles. A 
valid Iterator ID is always returned, even when an error occurs. In the case of an error, calling the 
cfidrlterNextNetBundleO function returns a Null OID. 

PARAMETERS 

portlnstBundle (input) The OID of a PortlnstBundle for which the NetBundles relationship is to be 
traversed. 

error (output) A pointer to die error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 
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ERROR CODES 

CFIDR_UNUSABLE_OID: 
portlnstBundle is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
portlnstBundle is not the OID of a PortlnstBundle. 

CFIDR_JNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDRJ^O_ERROR: 
no error occurred. 

PRE-CONDITIONS 

Returns all the NetBundles which are connected to the PortlnstBundle passed in via portlnstBundle. 
Essentially, this returns the NetBundles which directly or indirectly contain any NetScalars connected to 
PortlnstScalars directly or indirectly owned by the PostlnstBundle. 

POST-CONDITIONS 

The cfidrlterNextNetBundleO function returns the next NetBundle OID in the NetBundles relationship. 

If no objects are currently present in the NetBundles relationship, an error is not returned but the first 
call to cfidrlterNextNetBundleO returns a Null OID. 

REFERENCE 

cfidrlterNextNetO 
cfidrlterNextNetBundleO 



5.11.3 cfidrPortlnstBundleGetPortlnsts 

DECLARATION 

cfidrPortlnstsIdT cfidrPortInstBundleGetPortInsts( 
cfidrPortlnstBundleldT portlnstBundle, 
cfidrlterModeT mode, 
cfidrErrorT *enor) 

DESCRIPTION 

This function initiates a traversal of all of the Portlnsts (PortlnstBundles, PortlnstBusses, or 
PortlnstScalars) at die end of the Portlnsts relationship defined for the PortlnstBundle specified by 
portlnstBundle. 

RETURN VALUE 
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The return value is a cfidrPortlnstsWT referring to an Iterator ID that iterates over Portlnsts. A valid 
Iterator ID is always returned, even when an error occurs. In the case of an error, calling the 
cfidrlterNextPortlnstO function returns a Null OID. 

PARAMETERS 

portlnstBundle (input) The OID of a PortlnstBundle for which the Portlnsts relationship is to be 
traversed. 

mode (input) The mode that determines which Portlnsts are returned. The current valid values are 
CFIDRJTERJSCALARS, CFIDRJTERJBUNDLES, CFIDRJTERJTOP, and CFIDRJTER_ALL. 
See the Pre-Conditions below for more detail on how these modes behave. 

error (output) A pointer to the eiror returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
portlnstBundle is not a usable OID. 

CFIDR_INVALm_OBJECTTYPE: 
portlnstBundle is not the OID of an PortlnstBundle. 

CFIDR_INVALIDJTERMODE: 
mode is not a valid IterMode. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDRJsIOJERROR : 
no error occurred. 

PRE-CONDITIONS 

The Portlnsts returned depends on the mode argument specified. 
morfe=CFTORjrrERjrOP 

Returns only those Portlnsts (PortlnstBundles, PortlnstBusses, or PortlnstScalars) which are owned 
directly by the PortlnstBundle. 

morfe=CFIDRJTER_SCALARS 

Returns all the PortlnstScalars owned directly or indirectly by the PortlnstBundle. No PortlnstBundles 
are output with this mode. 

morfe==CFIDRjrrERJBUNDLES 

Returns all the PortlnstBundles owned directly or indirectly by the PortlnstBundle. No PortlnstScalars 
are output with this mode. 

mo</e=CFIDFUTER_ALL 



http://www.si2.org/si2 



6/23/2004 



Page 30 of 76 



Returns all the Portlnsts (PortlnstBundles, PortlnstBusses or PortlnstScalais) owned directly or 
indirectly by the PortlnstBundle. This is the union of all the Portlnsts returned by the 
CFIDRJTERJSCALARS and CFIDRJTTERJiUNDLES modes. 

Depth first recursion is used for all modes except CFIDRJTERJTOP. 
POST-CONDITIONS 

The cfidrlterNextPortlnstO function returns the next Portlnst OID in the Portlnsts relationship. 

If no objects are currently present in the Portlnsts relationship, an error is not returned but the first call 
to cfidrlterNextPortlnstO returns a Null OID. 

The Portlnst name scoping rules (inherited from the Port name scoping rules) state that Portlnst names 
are only unique within their immediate owner (either an Inst or a PortlnstBundle). Thus, two Portlnsts 
with the same name may exist and be completely different objects. Thus, Portlnsts returned via any 
mode except CFIDRJTERJTOP may have the same name but in fact be different objects. The 
cfidrObjectlsSameO function can be used to determine if any two of these Portlnsts are the same. 

REFERENCE 

cfidrlterNextPortlnstO 
cfidrObjectlsSameO 

cfidrPortBundleGetPortsO 



5.11.4 cfidrPortlnstBundleGetSize 

DECLARATION 

cfidrInt32T cfidrPortInstBundleGetSize( 
cfidrPortlnstBundleldT portlnstBundle, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the number of Ports currently in the specified portlnstBundle. This is only the 
number at the next level and not a count of the total number of scalars in the bundle. 

RETURN VALUE 
The return value is a cfidrInt32T. If an error occurs, a -1 is returned. 

PARAMETERS 
portlnstBundle (input) The OID of a PortlnstBundle. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 
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ERROR CODES 

CF©R_UNUSABLE_OID: 
portlnstBundle is not a usable Off). 

CFIDRJWVALIDjOBJECTTYPE: 
portlnstBundle is not the OID of a PortlnstBundle. 

CFIDR_INTERNAL_SYSTEM _ERROR: 
some other error occurred. 

CFff)R_NQ_ERROR: 
no error occurred. 

PRE-CONDITIONS 

PortlnstBundles are created only indirectly when Insts are created and the Describer NetlistView has 
PortBundles. The PortlnstBundle size is that of the Describer PortBundle. 

REFERENCE 

cfidrPortBundleGetSizeO 

cridrPortlnstGetDescriberO 

cfidrNetlistViewCreatelnstQ 



5.11.5 cfidrPortlnstBusGetStart 

DECLARATION 

cfidrInt32T cfidrportInstBusGetStart( 
cfidrPortlnstBusIdT portlnstBus, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the start attribute of the specified portlnstBus. This specifies the first index value 
for this bus. 

RETURN VALUE 
The return value is a cfidrInt32T. If an error occurs, a 0 is returned. 

PARAMETERS 
portlnstBus (input) The OID of a PortlnstBus. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
tiie memory used by this parameter. 
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ERROR CODES 

CFIDR_UNUSABLE_OID: 
portlnstBus is not a usable OID. 

CFIDR_JNVALID_OBJECTTYPE: 
portlnstBus is not the OID of a PortlnstBus. 

CFIDRJNTERNAL_SYSTEKORROR: 
some other error occurred. 

CFIDR^NOJERROR: 
no error occurred. 

PRE-CONDITIONS 

The start attribute of a PortlnstBus is that of the start attribute of the Describer PortBus. 
REFERENCE 

cfidrPortlnstGetDescriberO 
cfidrPortBusGetStartO 

cfidrNetlistViewCreatelnstO 

5.11.6 cfidrPortlnstBusGetStep 

DECLARATION 

cfidrInt32T cfidrPortInstBusGetStep( 
cfidrPortlnstBusIdT portlnstBus, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the step attribute of the specified portlnstBus. This attribute specifies the numeric 
increment between positions for the index. 

RETURN VALUE 

The return value is a cfidrInt32T. If an error occurs, a 0 is returned 

PARAMETERS 
portlnstBus (input) The OID of a PortlnstBus. 

error (output) A pointer to the error returned if this fiinction fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 
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CFIDR_UNUSABLE_OID: 
portlnstBus is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
portlnstBus is not the OID of a PortlnstBus. 

CFIDR_INTERNAL_SYSTEMLERROR: 
some other error occurred. 

CFIDR_J"JQ_ERROR: 
no error occurred. 

PRE-CONDITIONS 

The Step attribute of a PortlnstBus is that of the Describer PortBus. 
REFERENCE 

cfidrPortBusGetStepO 

cfidrPortlnstGetDescriberO 

cfidrNetlistViewCreatePortBusO 

5.11.7 cfidrPortlnstCheckDescriber [2] 

DECLARATION 

cfidrBooleanT cfidrPortInstCheckDescriber( 
cfidrPortlnstldT portlnst, 
cfidrErrorT *error) 

DESCRIPTION 

This function checks for discrepancies between Portlnst specified via portlnst and its Describer Port. 

If portlnst is a PortlnstBundle or Bus, checking is performed on all Portlnsts owned either directly or 
indirectly by the Portlnst (as returned by cfidrPortlnstBundleGetPortlnsts with mode ITER_ALL). 

[2] NOTE: This function can be written entirely using other DR-PI functions. 

RETURN VALUE 

If no discrepancies are found between the Portlnst and the Describer Port, CFIDRJFALSE is returned. 
Otherwise, CFIDR_TRUE is returned and the error output argument will denote the discrepancy. 

PARAMETERS 

portlnst (input) The OID of the Portlnst to check against its Describer Port. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
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the memory used by this parameter. 
ERROR CODES 

CFIDR_UNUSABLE_OID: 
portlnst is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
portlnst is not the OID of a Portlnst. 

CFIDRJDESCRIBER^VIEWJ^OTJOUND: 

could not find or access the Describer View for the Instance on which portlnst resides. 

CFIDR w DESCRIBERJ»ORTJ^OT_JOUND: 

there is no Port corresponding to portlnst on the Describer View. 

CFIDRJ>ORT_MEMBERS JDIFFER: 

portlnst is a bundle and the members differ from the members of the corresponding Describer 
PortBundle OR the corresponding Describer is a PortScalar. This error is also returned if the Portlnst is 
a PortlnstScalar, but the corresponding Describer is a PortBundle. This error is also returned if the 
owner of the describer of a Portlnst is not the same object as the describer of the owner of that Portlnst. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

POST-CONDITIONS 

If the Describer View is not opened yet, then this function will open it for CFE>R_READ. If the open 
fails, the error returned from this function will be the error returned from the failed open. 

REFERENCE 

cfidrNethstViewCreatelnstO 



5.11.8 cfidrPortlnstGetDescriber 

DECLARATION 

cfidrPortldT cfidrPortf nstGetDescriber( 
cfidrPortlnstldT portlnst, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the Port at the end of the Describer relationship for the Portlnst specified by 
portlnst. 



http://ww.si2.org/si2jublicafo 



6/23/2004 



Page 35 of 76 



RETURN VALUE 

The return value is a cfidrPortldT referring to the Port at the end of the Describer relationship If an 
error occurs, a Null OID is returned. 

PARAMETERS 

portlnst (input) The OID of the Portlnst whose Describer relationship is to be followed. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDPv_UNUSABLE_OID: 
portlnst is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
portlnst is not the OID of a Portlnst. 

CFIDRJ>ESCRIBER_VIEW_NOTJOUND: 

could not find or access the Describer View for the Inst on which portlnst resides. 
CFIDRJDESCRIBER_PORT_NOTJOUND: 

there is no Port corresponding to portlnst on the Describer View either because the Describer port does 

not exist or because it is inconsistent with the Portlnst due to scalar versus bundle of differing bundle 

membership. The function cfidrPortlnstCheckDescribeiO can be used for more information if this error 
occurs. 

CFIDRJNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

If the Describer View is not opened yet, then this function will open it for CFIDR_READ. If the open 
fails, the error returned from this function will be the error returned from the failed open. 

5.11.9 cfidrPortlnstGetDescriberName [2] 

DECLARATION 

cfidrStringT cfidrPortInstGetDescriberName( 
cfidrPortlnstldT portlnst, 
cfidrErrorT *error) 

DESCRIPTION 
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This function returns the DescriberName (derived) attribute of the Portlnst specified by portlnst. 
[2] NOTE: this function can be written entirely using other DR-PI functions. 
RETURN VALUE 

The return value is a cfidrStringT representing the string value of the DescriberName attribute. On error, 
the function returns "". 

PARAMETERS 

portlnst (input) The OID of the Portlnst whose DescriberName attribute is desired. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
portlnst is not a usable OID. 

CFIDR_JNVALID_OBJECTTYPE: 
portlnst is not the OID of a Portlnst 

CTIDRJDESCRIBER_VIE W_NOT JFOUND: 

could not find or access the Describer View for the Inst on which portlnst resides. 

CFIDR_DESCRIBER_pORT_NOT J?OUND: 

there is no Port corresponding to portlnst on the Describer View. 

CFIDR_JNTERNAL_SYSTEM_£RROR: 
some other error occurred. 

CFIDR_NOJERROR: 
no error occurred. 

POST-CONDITIONS 

If the Describer View is not opened yet, then this function will open it for CFIDR_READ. If the open 
fails, the error returned from this function will be the error returned from the failed open. 

REFERENCE 

cfidrNamedObjectGetNameO 
cfidrPortlnstGetDescriberO. 

5.11.10 cfidrPortlnstGetOwner 

DECLARATION 
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cfidrObjectldT cfidrPortInstGetOwner( 
cfidrPortlnstldT portlnst, 
cfidrEnorT *error) 

DESCRIPTION 

This function returns the object (Instance or PortlnstBundle) at the end of the Owner relationship for the 
Portlnst specified by portlnst. The Owner relationship is defined when an object is created and cannot 
be modified. 

RETURN VALUE 

The return value is a cfidrObjectldT referring to the Inst or the PortlnstBundle at the end of the Owner 
relationship. If an error occurs, a Null OID is returned. 

PARAMETERS 

portlnst (input) The OID of the Portlnst whose Owner relationship is to be followed. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
portlnst is not a usable OID. 

CFIDRJNVALID_OBJECTTYPE : 
portlnst is not the OID of a Portlnst 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDRJNOJERROR: 
no error occurred. 

POST-CONDITIONS 

Use the cfidrObjectGetObjectTypeO function to determine the Owner's object type. 
REFERENCE 

cfidrObjectGetObjectTypeO 

5.11.11 cfidrPortlnstScalarGetDescriberDirection [2] 

DECLARATION 

cfidrPortDirectionT 
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cfidrPortInstScalaiGetDescriberDirection( 
cfidrPortlnstScalarldT portlnstScalar, 
cfidrErrorT *enx>r) 

DESCRIPTION 

This function returns the DescriberDirection (derived) attribute of the PortlnstScalar specified by 
portlnstScalar. 

[2] NOTE: this function can be written entirely using other DR-PI functions. 
RETURN VALUE 

The return value is a cfidrPortDirectionT enumerated type representing the value of the 
DescriberDirection attribute. 

On error the function returns CFIDRJUNDEFINEDJPORTDIRECTION. 
PARAMETERS 

portlnstScalar (input) The OID of the PortlnstScalar whose DescriberDirection attribute is desired. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
portlnstScalar is not a usable OID. 

CFIDRJNVALID_OBJECTTYPE: 
portlnstScalar is not the OID of a PortlnstScalar. 

CFIDR_OESCRIBER_VIEW_NOTJ 7 OUND: 

could not find or access the Describer View for the Inst on which portlnstScalar resides. 
CFIDR_DESCRIBERJ > ORT_NOTJ ? OUND: 

there is no PortScalar corresponding to portlnstScalar on the Describer View. 

CFIDR_INTERNAL_SYSTEM _JERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

POST-CONDITIONS 

If the Describer View is not opened yet, then this function will open it for CFIDRJREAD. If the open 
fails, the error returned from this function will be the error returned from the failed open. 
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REFERENCE 

cfidrPortlnstGetDescriberO. 



5.11.12 cfldrPortlnstScalarGetNetScalar 

DECLARATION 

cfidrNetScalarldT cfidrPortInstScalarGetNetScalar( 
cfidrPortlnstS calarldT portlnstScalar, 
cfidrErrorT *error) 

DESCRIPTION 

This function retrieves the NetScalar at the end of the NetScalar relationship defined for the 
PortlnstScalar specified by portlnstScalar. 

RETURN VALUE 

The return value is a cfidrNetScalarldT referring to the NetScalar at the end of the NetScalar 
relationship. If an error occurs or if there is no NetScalar attached to this PortlnstScalar, a Null OID is 
returned. 

PARAMETERS 

portlnstScalar (input) The OID of the PortlnstScalar containing the NetScalar relationship which is 
being traversed. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
portlnstScalar is not a usable OID. 

CFIDR_JNVALID_OBJECTTYPE: 
portlnstScalar is not the OID of a PortlnstScalar 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

REFERENCE 

cfidrNetGetPortlnstsO 
cfidrNetGetPortsO 
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Property Functions 

5.12 Property Functions 

5.12.1 cfidrPropGetBoolean Value 

DECLARATION 

cfidrBooleanT cfidrPropGetBooleanValue( 
cfidrPropIdT prop, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the Boolean Value attribute of the Property specified by prop. 
RETURN VALUE 

The return value is either CFIDRJTRUE or CFIDR_FALSE. If an error occurs the function returns 
CFIDRJFALSE. 

PARAMETERS 

prop (input) The OID of the Property whose Boolean Value attribute is desired. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
prop is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 

prop is not the OID of a Boolean-valued Property. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred 

REFERENCE 

cfidrPropSetBooleanValueO 



http://www.si2.org/si2 jublications/htmlSpecs/DR/part5b.fm4.html 



6/23/2004 



Page 41 of 76 



5.12.2 cfidrPropGetFloat32Value 

DECLARATION 

cfidrFloat32T cfidrPropGetFloat32Value( 
cfidrPropIdT prop, 
cfidrErrorT *enor) 

DESCRIPTION 

This function returns the Float32 Value attribute of the Property specified by prop. 
RETURN VALUE 

The return value is a cfidrFloat32T representing a 32-bit floating point number. If an error occurs the 
function returns 0.0. 

PARAMETERS 

prop (input) The OID of the Property whose Float32 Value attribute is desired. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
prop is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 

prop is not the OID of a Float32-valued Property. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_J*0_ERROR: 
no error occurred. 

POST-CONDITIONS 

The float returned is guaranteed to be in the range CFIDR_MIN_FLOAT32 to 
€FIDR31AXJ ? L0AT32. 

REFERENCE 

cfidrPropSetFloat32ValueO 



5.12.3 cfidrPropGetInt32Value 
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DECLARATION 

cfidrInt32T cfidrPropGetInt32Value( 
cfidrPropIdT prop, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the Int32 Value attribute of the Property specified by prop. 
RETURN VALUE 

The return value is a cfidrInt32T representing a 32-bit integer number. If an error occurs the function 
returns 0. 

PARAMETERS 

prop (input) The OID of the Property whose Int32 Value attribute is desired. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
tiie memory used by this parameter. 

ERROR CODES 

CFIDRJJNUSABLE_OID: 
prop is not a usable OID. 

CFIDRJNVALIDjOBJECTTYPE: 

prop is not the OID of a Int32- valued Property. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

POST-CONDITIONS 

The integer returned is guaranteed to be in the range CFIDRJvHNJNT32 to CFIDR_MAX_INT32 . 
REFERENCE 

cfidrPropSetInt32Value0 

5.12.4 cfidrPropGetOwner 

DECLARATION 

cfidrObjectldT cfidrPropGetOwner( 
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cfidrPropWT prop, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the object at the end of the Owner relationship for the Property specified by prop. 
The Owner relationship is defined when an object is created and cannot be modified. 

RETURN VALUE 

The return value is a cfidrObjectldT referring the object at the end of the Owner relationship. Since any 
object can have properties, the owner can be any object type. If an error occurs, a Null OID is returned. 

PARAMETERS w 

prop (input) The OID of the Prop whose Owner relationship is to be followed. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
prop is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
prop is not the OID of a Property. 

CFIDR__INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

POST-CONDITIONS 

Use the cfidrObjectGetObjectTypeO function to determine the Owner's object type. 
REFERENCE 

cfidrObjectCreatePropO 
cfidrObjectGetObjectTypeO 

5.12.5 cfidrPropGetStringValue 

DECLARATION 

cfidrStringT cfidrPropGetStringValue( 
cfidrPropIdT prop, 



http://www.si2.org/si2jubli<»tion 



6/23/2004 



Page 44 of 76 



cfidrErrorT ♦error) 
DESCRIPTION 

This function returns the String Value attribute of the Property specified by prop. 
RETURN VALUE 

The return value is a cfidrStringT representing a string. If an error occurs the function returns (the 
empty string). 

PARAMETERS 

prop (input) The OID of the Property whose String Value attribute is desired. 

error (output) A pointer to the error returned if this function faUs. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
prop is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 

prop is not the OID of a String-valued Property. 

CFIDR_INTERNAL_SYSTEM JERROR: 
some other error occurred. 

CFIDR_NO_JiRROR: 
no error occurred. 

POST-CONDITIONS 

There are no restrictions on the length or characters used in the string. The memory for the string is 
managed by die DR-PI. The string's value remains valid until the next execution of any PI function 
which has a cfidrStringT return value. 

REFERENCE 

cfidrPropSetStringValueO 



5.12.6 cfidrPropGetValueType 

DECLARATION 

cfidrValueTypeT cfidrPropGetValueType( 

cfidrPropIdTprop, 

cfidrErrorT *error) 
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DESCRIPTION 

This function returns the ValueType attribute of the Property specified by prop. 
RETURN VALUE 

The return value is a cfidrValueTypeT enumerated type representing the value of the ValueType 
attribute. If an error occurs, the function returns CFIDR_UNDEFINED_VALUETYPE. 

PARAMETERS 

prop (input) The OID of the Property whose ValueType attribute is desired. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
prop is not a usable OID. 

CFIDR^INVALID.OBJECTTYPE: 
prop is not the OID of a Property. 

CFIDRJNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

The value type of a Prop is set by the type of the particular value set for the Prop. See the 
cfidrPropSet..ValueO functions. 

REFERENCE 

cfidrPropSet..ValueO functions. 



5.12.7 cfidrPropSetBooleanValue 

DECLARATION 

cfidrVoidT cfidrPropSetBooleanValue( 
cfidrPropIdTprop, 
cfidrBooleanT value, 
cfidrErrorT *error) 

DESCRIPTION 
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This function sets the Boolean Value attribute for the Property specified via prop. 
PARAMETERS 

prop (input) The OID of the Property to which the Value attribute is to be set. 
value (input) The desired Boolean value for the Value attribute of prop. 

Z2^3K£S£ retUmed failS ' 116 * «^-* fe «■>— * 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
prop is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
prop is not the OID of a Property. 

CFIDR_READ_ONLY: 

the containing object (Lib or View) has not been opened for update. 

CFIDR_IN VALIDJVALUE : 
value is not a valid Boolean value. 

CFIDR_INTERNAL_SYSTEMJERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

defeuft val^ 8Uinent mUSt ^ ^ CFIDR - TRUE or CFIDRJFALSE. Any other value will not set the 
POST-CONDITIONS 

SfcetoS^f the < chang^ be "* t0 * persistent Purgin8 me before savul S il w 111 result 

If the Property's Value attribute was other than a Boolean, the setting still takes place and the ValueType 
is changed to CFIDRJOOLEAN. yv 

REFERENCE 
cfidrObjectCreatePropO 



5.12.8 cfidrPropSetFloat32Value 

http://www.si2.org/si2jublications/htalSpecs/DR/part5b.fm4A 



6/23/20O4 



Page 47 of 76 



DECLARATION 

cfidrVoidT cfidrPropSetFloat32Value( 
cfidrPropWTprop, 
cfidrFloat32T value, 
cfidrErrorT *enor) 

DESCRIPTION 

This function sets the Float32 Value attribute for the Property specified via prop. 
PARAMETERS 

prop (input) The OID of the Property to which the Value attribute is to be set 
value (input) The 32-bit floating point number to set the Value attribute to. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
prop is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
prop is not the OID of a Property. 

CFIDR_READ_ONLY: 

the containing object (Lib or View) has not been opened for update. 

CFIDR_JNVALID_VALUE: 
value is not a valid Float32 value. 

CFIDR_INTERNAL_SYSTEM JBRROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

The value argument must be within the range CFIDRJMIN_pLOAT32 to CFIDR3IAX_FLOAT32. 
POST-CONDITIONS 

The updated object must be saved in order to be persistent. Purging the object before saving it will result 
in the loss of the changes. 

If the Property's Value attribute was other than a Float32, the setting still takes place and the ValueType 
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is changed to CFEDR_FLOAT32. 
REFERENCE 

cfidrObjectCreatePropO 

5.12.9 cfidrPropSetInt32Value 

DECLARATION 

cfidrVoidT cfidrPropSetInt32Value( 
cfidrPropIdT prop, 
cfidrInt32T value, 
cfidrErrorT *error) 

DESCRIPTION 

This function sets the Int32 Value attribute for the Property specified via prop. 
PARAMETERS 

prop (input) The OID of the Property to which the Value attribute is to be set 
value (input) The 32-bit integer number to set the Value attribute to. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
prop is not a usable OID. 

» 

CFIDR_INVALID_OBJECTTYPE: 
prop is not the OID of a Property. 

CFIDR_READ_ONLY: 

the containing object (Lib or View) has not been opened for update. 

CFIDR_JNVALID_VALUE: 
value is not a valid Int32 value. 

CFIDR_INTERNAL_SYSTEMJERROR: 
some other error occurred. 

CFIDR_NQ_ERROR: 
no error occurred. 

PRE-CONDITIONS 
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The value argument must be within the range CFIDRJV1INJNT32 to CFEDR_MAX_INT32. 
POST-CONDITIONS 

The updated object must be saved in order to be persistent. Purging the object before saving it will result 
in the loss of the changes. 

If the Property's Value attribute was other than a Int32, the setting still takes place and the ValueTvve is 
changed to CFIDRJNT32. 

REFERENCE 
cfidrObjectCreatePropO 



5.12.10 cfidrPropSetStringValue 

DECLARATION 

cfidrVoidT cfidrPropSetStringValue( 
cfidrPropIdT prop, 
cfidrStringT value, 
cfidrErroiT *error) 

DESCRIPTION 

This function sets the String Value attribute for the Property specified via prop. 
PARAMETERS 

prop (input) The OID of the Property to which the Value attribute is to be set. 

value (input) The string to set the Value attribute to. The caller is responsible for managing the memory 
of this string. 

NOTE: DR-PI functions which return cfidrStringT values guarantee those strings to not be updated 
until the next call to a PI function that returns another cfidrStringT. These strings can be used as the 
value argument because the cfidrPropSetStringValueO function will not affect these strings returned 
from other PI functions. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDRJJNUSABLE_OID: 
prop is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
prop is not the OID of a Property. 
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CFIDRJtEAD_ONLY: 

the containing object (Lib or View) has not been opened for update. 

CFIDRJNVALID.VALUE: 
value is not a valid String. 

CFIDRJNTERNALJSYSTEM.ERROR: 
some other error occurred. 

CFIDR^NOJERROR: 
no error occurred. 

PRE-CONDITIONS 

No limitations exists as far as the length or character set used in the string defined by the value 
argument. 

POST-CONDITIONS 

The updated object must be saved in order to be persistent. Purging the object before saving it will result 
m the loss of the changes. 

^)Si tf sssr attribnte was other tban • string ' sm tekes *~ *«* 

REFERENCE 
cfidrObjectCreatePropO 

5.13 View Functions 



5.13.1 cfidrEncapsuIatedViewGetKey 

DECLARATION 

cfidrStringT cfidrEncapsulatedViewGetKey( 
cfidrEncapsulatedViewIdT encapsulatedView, 
cfidrEnnoiT *error) 

DESCRIPTION 

This function returns the Key attribute of the EncapsulatedView specified by encapsulatedView. 
RETURN VALUE 

The return value is a cfidrStringT representing the value of the Key attribute. On error the string 
M CFIDR_UNDEFINEDJCEY" is returned. 
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PARAMETERS 

encapsutatedView (input) The OID of the EncapsulatedView whose Key attribute is desired. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for 
the memory used by this parameter. 

ERROR CODES 

CFIDR w UNUSABLE_OID: 
encapsutatedView is not a usable OID. 

CFIDRJNVALIDjOBJECTTYPE: 
encapsulatedView is not the OID of a EncapsulatedView. 

CFIDEL.INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NOJ3RROR: 
no error occurred. 

PRE-CONDITIONS 

The Key attribute is set by the cfidrCellCreateEncapsulatedViewO function. 
REFERENCE 

cfidrCellCreateEncapsulatedViewO 



5.13.2 cfidrNetlistViewCreatelnst 

DECLARATION 

cfidrlnstldT cfidrNetlistViewCreatelnst 
cfidrNetlistViewIdT owner, 
cfidrNetlistViewIdT describer, 
cfidrStringT name, 
cfidrErrorT *error) 

DESCRIPTION 

This function creates an Inst object owned by the NetlistView specified via owner. The Inst is an 
instantiation of another NetlistView specified via describer. The Inst is referred to by name. 

RETURN VALUE 

The return value is a cfidrlnstldT which refers to the Inst object just created. If an error occurs, a Null 
OID is returned. 
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PARAMETERS 

owner (input) The OID of the NetlistView owning the Inst being created. 
describer (input) The OID of the NetlistView describing the Inst being created. 
name (input) The string representing the Name of the Inst to create. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
owner is not a usable OID. 

CFIDR_INVALID_OB JECTTYPE : 
owner is not the OID of a NetlistView. 

CFIDRJREAD_ONLY: 

the View has not been opened for update. 

CFIDR_UNUSABLE_DESCRIBER_OID: 

describer is not a usable OID. 

CFIDRJNVALID_DESCRIBER_TYPE: 
describer is not the OID of a NetlistView. 

CFIDR_B-ESCRIBER_RECURSION: 

describer is the same NetlistView object as owner or recursively contains an Instance of owner. 
CFIDRJNVALID _NAME: 

the name parameter is not a valid string or is not a legal name. 

CFIDR__OB JECT_ALREADY_EXISTS : 
an Inst with the Name name already exists. 

CFIDR_INTRA_CELL_INSTANTIATION: 

The owner of describer is the same object as the owner of owner. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

The NetlistView OID specified by describer must refer to a usable NetlistView (i.e., top-down design by 
creating Insts without a describer NetlistView is disallowed). This also implies that the describer 
NetlistView has been previously created or opened. 
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The name argument must conform to the character set rules for name strings. 

An Inst with the given name cannot already exist in the NetlistView specified by owner. 

POST-CONDITIONS 

Creating an Inst automatically creates Portlnsts (PortlnstBundles, PortlnstBusses, and PortlnstScalars) 
owned by the Inst. These Portlnsts correspond 1-for-l to Ports in the describer NetlistView. They may 
be retrieved as soon as the Inst is successfully created. 

REFERENCE 

cfidrNetlistViewGetlnstsQ 

5.13.3 cfidrNetlistViewCreateNetBundle 

DECLARATION 

cfidrNetBundleIdTcfidrNetlistViewCreateNetBundle( 
cfidrNetlistViewIdT owner, 
cfidrStringT name, 
cfidrErrorT *error) 

DESCRIPTION 

This function creates a NetBundle object owned by the NetlistView specified via owner. The NetBundle 
is referred to by name. 

RETURN VALUE 

The return value is a cfidrNetBundleldT referring to the NetBundle object just created. If an error 
occurs, a Null OID is returned. 

PARAMETERS 

owner (input) The OID of the NetlistView owning the NetBundle being created. 

name (input) The string representing the Name of the NetBundle being created. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR__UNUSABLE_OID: 
owner is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
owner is not the OID of a NetlistView. 
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CFIDRJREADjONLY: 

the owner View has notbeen opened for update. 

CFIDR_INVALIDJsIAME: 

the name parameter is not a valid string or is not a legal name. 
CFIDR^AME _JN_USE: 

the name parameter specifies a name already in use in the same name scope but not for a NetBundle. 

CFIDR w OBJECTjU.READY_EXISTS: 

a NetBundle with the same name already exists. 

CFIDR_JNTERNAL_SYSTEMJERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

The name argument must conform to the character set rules for name strings. 

A Net (NetScalar, NetBundle, or NetBus) with the given name cannot already exist in the NetlistView 
specified by owner. 

POST-CONDITIONS 

The newly created NetBundle will initially have no members and a size of zero. 

The NetBundle created by this function can later be inserted into one or more NetBundle(s). 

REFERENCE 

cfidrNetBundleGetNetsO 
cfidrNetBundlelnsertNetO 
cfidrNetBundleRemoveNetO 
cfidrNetlistViewGetNetsO 

5.13.4 cfidrNetlistViewCreateNetBus 

DECLARATION 

cfidrNetBusIdT cfidrNetlistViewCreateNetBus( 

cfidrNetlistViewIdT owner, 

cfidrStringT name, 

cfidrInt32T start 

cfidrInt32T step 

cfidrErrorT *error) 
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DESCRIPTION 

This i function xreates a NetBus object owned by the NetlistView specified via owner. The NetBus name 
attribute is set to name. The NetBus start attribute is set to start. The NetBus step attribute is set to step. 

RETURN VALUE 

Null O^rtuuifed cfidrNetBusIdT referrin 8 to Ae NetBus object just created. If an error occurs, a 
PARAMETERS 

owner (input) The OID of the NetlistView owning the NetBundle being created. 
name (input) The string representing the name of the NetBundle being created. 
start (input) The Int32 defining the index of position 0 in the bus. 

step (input) The Int32 defining the difference in indexes of positions n and n+1 in the bus. This number 
must be non-zero. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. <u.u^uu e 

ERROR CODES 

CFIDRJUNUSABLE.OID: 
owner is not" a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
owner is not the OID of a NetlistView. 

CFIDR_READ_ONLY: 

the owner View has not been opened for update. 

CFIDR_INVALID_NAME: 

the name parameter is not a valid string or is not a legal name. 
CFIDRJNAME_IN_USE: 

the name parameter specifies a name already in use in the same name scope but not for a NetBus. 

CFIDR_OBJECT_ALREADY_EXISTS: 
a NetBus with the same name already exists. 

CFIDR_INVALID_VALUE 
Step is 0. 

CFIDR_INTERNAL_SYSTEMJERROR: 
some other error occurred. 
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CFIDR^NOJERROR: 
no error occurred. 

PRE-CONDITIONS 

The name argument must conform to the character set rules for name strings. 

A Net (NetScalar, NetBundle, or NetBus) with the given name cannot already exist in the NetlistView 
specified by owner. 

POST-CONDITIONS 

The newly created NetBus will initially have no members and a size of 0. 

The NetBus created by this function can later be inserted into one or more NetBundle(s). 

The Start and Step attributes may be changed later by use of the cfidrNetBusSetStartO and 
cfidrNetBusSetStepO functions. 

REFERENCE 

cfidrNetBundleGetSizeO 

cfidrNetBundleGetNetsO 

cfidrNetBundlelnserfNetO 

cfidrNetBundleRemoveNetQ 

cfidrNetBusGetStartO 

cfidrNetBusGetStepO 

CfidrNetBusSetStartO 

CfidrNetBusSetStepO 

cfidrNetiistViewGetNetsQ 



5.13.5 cfidrNetUstViewCreateNetScalar 

DECLARATION 

cfidrNetScalarldT cfidrNetlistViewCreateNetScalar( 
cfidrNetlistViewIdT owner, 
cfidrStringT name, 
cfidrErrorT *error) 

DESCRIPTION 

This function creates a NetScalar object owned by the NetlistView specified via owner. The NetScalar is 
referred to by name. 

RATIONALE 

This function only allows NetScalars to be created and owned by the NetlistView. The NetScalar can be 
subsequently contained in a NetBundle. 
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RETURN VALUE 

The return value is a cfidrNetScalarldT referring to the NetScalar just created. If an error occurs, a Null 
U1D is returned. 

PARAMETERS 

owner (input) The OID of the NetlistView owning the NetScalar to be created. 
name (input) The string representing the name of the NetScalar. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
owner is not a usable OID. 

CFIDR_JNVALID_OBJECTTYPE: 
owner is not the OID of a NetlistView. 

CFIDR_READ_ONLY: 

die owner View has not been opened for update. 

CFIDR_IN VALID_NAME : 

the name parameter is not a valid string or is not a legal name. 
CFIDR__NAME_IN_USE: 

the name parameter specifies a name already in use in the same name scope but not for a NetScalar. 

CFIDR_OBJECT_ALREADY_EXISTS: 

a NetScalar with the same name already exists. 

CFIDRJNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

The name argument must conform to the character set rules for name strings. 

A Net (NetScalar, NetBundle, or NetBus) with the given name cannot already be owned by the 
NetiistView specified by owner. 

POST-CONDITIONS 

The NetScalar created by this function can be later inserted into one or more NetBundle(s). 
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to change a"' attribUte ^ t0 CFIDIU?ALSE Use ** function cfidrNetScalarSetlsGlobalO 

REFERENCE 

cfidrNetScalarSetlsGlobalO 

cfidrNetlistViewGetNetsO 

cfidrNetBundleGetNetsO 

cfidrNetBundlelnsertNetO 

cfidrNetBundleRemoveNetO 

5.13.6 cfidrNetlistViewCreatePortBundle 

DECLARATION 

cfidrPortBundleIdTcfidrNetlistViewCreatePortBundle( 
cfidrNetlistViewIdT owner, 
cfidrStringT name, 
cfidrInt32T position, 
cfidrErrorT *error) 

DESCRIPTION 

This function creates a PortBundle object owned by the NetiistView specified via owner. 
RETURN VALUE 

The return value is a cfidrPortBundleldT referring to the PortBundle object just created. If an error 
occurs, a Null OID is returned. 

PARAMETERS 

owner (input) The OID of the NetiistView owning the PortBundle being created. 

name (input) The string representing the name of the PortBundle being created. 

position (input) The integer specifying the position of the PortBundle in the list of Ports owned by 
owner. A position value less than 0 or greater than or equal to the number of ports indicates the new 
PortBundle is put at end of the list Any other value, including 0, indicates the actual position in the list. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
owner is not a usable OID. 

CFIDRJNVALID_OBJECTTYPE: 
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owner is not the OID of a NetlistView. 

CFIDR_READ_ONLY: 

the owner View has not been opened for update. 

CFIDRJNVALID_NAME: 

the name parameter is not a valid string or is not a legal name. 
CFI DR_N AME_IN_US E : 

the name parameter specifies a name already in use in the same name scope but not for a PortBundle. 

CFIDR_OB JECT_ALREADY_EXISTS : 

a PortBundle with the same name already exists for this owner. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

The name argument must conform to the character set rules for name strings. 

A Port named name that is owned by the same NetlistView as specified by owner cannot already exist. 
POST-CONDITIONS 

The PortBundle is created with no members initially. Later, Ports or PortBundles may either be created 
m or have their owner changed to be this PortBundle. Furthermore, this PortBundle may later have its 
owner changed to a PortBundle instead of the NetlistView. 

The PortBundle is created and added to the list of Ports owned by the NetlistView specified by owner at 
the position specified by position. If position = 0, the new PortBundle will be added as the first member 
of the list If position is less than 0 or greater than or equal to the number of members in the list, the new 
PortBundle is appended to the end of the list Otherwise, the PortBundle is inserted at the specified 
position (0 based). The position of all Ports whose positions were greater than or equal to position, will 
have their position incremented by 1. For example, presume a NetlistView initially has Ports: 
A,B,C0,1,2. 

Adding a new member X at position 1 results in: 
A,X,B,C0, 1,2 

Note that B had position 1 before and has position 2 after X is created. 

Adding X at position 0 causes X to be at the beginning of the list: 
X, A, B, CO, 1,2 

Adding X at an invalid position such as -1 (or any value greater than 4) causes creation of the new 
member at the end of the list: 
A, B, CO, 1, 2, X 
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REFERENCE 

cfidrPortBundleCreatePortBundleO 
cridrPortBundleCreatePortScalarO 

cfidrPortBundleGetOwneiO 

cfidrPortBundleGetPortsO 

cfidrPortSetOwnerPortBundleO 

cfidrPortSetOwnerViewO 

cfidrNetlistViewGetPortsO 



5.13.7 cfidrNetlistViewCreatePortBus 

DECLARATION 

cfidrPortBusIdT cfidrNetlistViewCreatePortBus( 

cfidrNetiistViewIdT owner, 

cfidrStringT name, 

cfidrInt32T position 

cfidrint32T start 

cfidrInt32T step 

cfidrErrorT *error) 

DESCRIPTION 

This function creates a PortBus object located at the position position in the list of Ports owned by the 
NethstView specified via owner. The PortBus Name attribute is set to name. The PortBus Start attribute 
is set to start. The PortBus Step attribute is set to step. 

RETURN VALUE 

The return value is a cfidrPortBusIdT referring to the PortBus object just created. If an error occurs, a 
Null OID is returned. 

PARAMETERS 

owner (input) The OID of the NedistView owning the PortBus being created. 
name (input) The string representing the name of the PortBus being created. 

position (input) The integer specifying the position of the PortBus in the list of Ports owned by owner. A 
position value less than 0 or greater than or equal to the number of ports indicates the new PortBus is put 
at end of the list. Any other value, including 0, indicates the actual position in the list. 

start (input) The Int32 defining the index of position 0 in the bus. 

step (input) The Int32 defining the difference in indexes of positions n and n+1 in the bus. This number 
must be non-zero. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
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the memory used by this parameter. 
ERROR CODES 

CFIDFLUNUSABLEjOID: 
owner is not a usable OID. 

CFIDRJNVALID_OBJECTTYPE: 
owner is not the OID of a NetlistView. 

CFIDR_READ_ONLY: 

the owner View has not been opened for update. 

CFIDRJNVALIDjqAME: 

the name parameter is not a valid string or is not a legal name. 
CFIDR_JsfAME_JN_USE: 

the name parameter specifies a name already in use in the same name scope but not for a PortBus. 

CFIDR_OBJECT_ALREADY_EXISTS: 
a PortBus with the same name already exists. 

CFIDR_JNVALID_VALUE 
Step is 0. 

CFIDR w INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR^NOJERROR: 
no error occurred. 

PRE-CONDITIONS 

The name argument must conform to the character set rules for name strings. 

A Port (PortScalar, PortBundle, or PortBus) with the given name cannot already exist in the NetlistView 
specified by owner. 

POST-CONDITIONS 

The newly created PortBus will initially have no members and a size of 0. 

The PortBus created by this function can later be changed to have a PortBundle as its owner usine 
cfidrPortBundleSetOwnerPortBundleO 

The Start and Step attributes may be changed later by use of the cfidrPortBusSetStartO and 
cfidrPortBusSetStepO functions. 

REFERENCE 
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cfidrPortBundleGetSizeO 

cfidrPortBundleGetNetsO 

cfidrPortBundleSetOwnerPortBundleO 

cfidrPortBundleSetOwnerViewO 

cfidrPortBusGetStartO 

cfidrPortBusGetStepO 

cfidrPortBusSetStartO 

cfidrPortBusSetStepO 

cfidrNetlistViewGetPortBundlesO 



5.13.8 cfidrNetlistViewCreatePortScalar 

DECLARATION 

cfidrPortScalarIdTcfidrNetlistViewCreatePortScalar( 

cfidrNetlistViewIdT owner, 

cfidrStringT name, 

cfidrint32T position, 

cfidrPortDirectionT direction, 

cfidrErrorT *error) 

DESCRIPTION 

This function creates a PortScalar object owned by the NetlistView specified via owner and located at 
position in the list of Ports owned by owner. The PortScalar Name attribute is set to name. The 
PortScalar Direction attribute is set to direction. 

RATIONALE 

The PortScalar is created with all required attributes set including the derived attribute of position. 
RETURN VALUE 

The return value is a cfidrPortScalarldT referring to the PortScalar just created. If an error occurs a Null 
OID is returned. 

PARAMETERS 

owner (input) The OID of the NetlistView owning the PortScalar to be created. 
name (input) The string representing the name of the PortScalar. 

position (input) The integer specifying the position of the PortScalar in the list of Ports owned by owner. 
A position value less than 0 or greater than or equal to the number of ports indicates the new Port is put 
at end of the list. Any other value, including 0, indicates the actual position in the list. 

direction (input) The Direction attribute to assign to the created PortScalar. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
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the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
owner is not a usable OID. 

CFIDRJNVALID_OBJECTTYPE: 
owner is not the OID of a NetlistView. 

CFIDR_READ_ONLY: 

the owner View has not been opened for update. 

CFIDR_JNVALID_NAME: 

the name parameter is not a valid string or is not a legal name. 
CFIDR_NAME_IN_USE: 

the name parameter specifies a name already in use in the same name scope but not for a PortScalar. 

CFIDR_OBJECT ^ALREADY ^EXISTS: 

a PortScalar with the same name already exists for owner. 

CFIDR_JNVALIDJ5IRECTION: 
direction is not a legal PortDirection. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

The name argument must conform to the character set rules for name strings. 

A Port (PortScalar, PortBundle, or PortBus) with the given name cannot already be owned by the 
NetlistView specified by owner. However, a Port with the same name may exist in a PortBundle. This is 
allowed since the scope of Port names is the owning NetlistView or the owning PortBundle. 

The owner of the PortScalar created by mis function can be later be changed to a PortBundle provided 
no other member of that PortBundle has the same name. 

POST-CONDITIONS 

The PortScalar is created and added to the list of Ports owned by the NetlistView specified by owner at 
the position specified by position. If position = 0, the new PortScalar will be added as the first member 
of the list If position is less than 0 or greater than or equal to the number of members in the list, the new 
PortScalar is appended to the end of the list. Otherwise, the PortScalar is inserted at the specified 
position (0 based). The position of all Ports whose positions were greater than or equal to position, will 
have their position incremented by 1 . For example, presume a NetlistView has Ports: 
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A, B, CO, 1,2. 

Adding a new member X at position 1 results in- 
A, X, B, CO, 1, 2 

Note that B had position 1 before and has position 2 after X is created. 

Adding X at position 0 causes X to be at the beginning of the list 
X, A B, CO, 1,2 

Adding X at an invalid position such as -1 (or any value greater than 4) causes creation of the new 
member at the end of the list: 
A B, CO, 1.2.X 

REFERENCE 

cfidrPortBundleCreatePortBundleO 

cridrPortBundleCreatePortScalarO 

cfidrPortBundleGetOwnerO 

cfidrPortBundleGetPortsO 

cfidrPortSetOwnerPortBundleO 

cfidrPortSetOwnerViewO 

cfidrNetlistViewCreatePortBundleO 

cfidrNetlistViewGetPortsO 

5.13.9 cfidrNetUstViewFindlnstByName 

DECLARATION 

cfidrlnstldT cfidrNetlistViewFindInstByName( 
cfidrNetlistViewIdT netlistView, 
cfidrStringTname, 
cfidrErroiT *error) 

DESCRIPTION 

This function returns the Inst with the specified name that is within the Insts relationship defined for the 
NetlistView specified by netlistView. 

RETURN VALUE 

The return value is a cfidrlnstldT referring to the Inst just found. If an error occurs, a Null OID is 
returned. 

PARAMETERS 

netlistView (input) The OID of the NetlistView from which the Inst is to be found, 
name (input) The name of the Inst. 
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error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
memory for this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
netlistView is not a usable OID. 

CFrDRJNVALID_OBJECTTYPE: 
netlistView is not the OID of a NetlistView. 

CFIDRJNVALID^NAME: 

the name parameter is not a valid string or is not a legal name. 

CFIDR_OB JECT_NOT_FOUND : 
no Inst with the specified name exists. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_JNO_ERROR: 
no error occurred. 



5.13.10 cfidrNetlistViewFindNetByName 

DECLARATION 

cfidrNetldT cfidrNetlistViewFindNetByName( 
cfidrNetlistViewIdT netlistView, 
cfidrStringT name, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the Net (either NetBundle or NetScalar) with the specified name that is within the 
Nets relationship defined for the NetlistView specified by netlistView. All Nets are scoped to the 
NetlistView, therefore Nets contained in NetBundles are also searched by mis function. 

RETURN VALUE 

The return value is a cfidrNetldT referring to the Net just found. If an error occurs, a Null OID is 
returned. 

PARAMETERS 

netlistView (input) The OID of the NetlistView from which the Net is to be found, 
name (input) The name of the Net. 
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error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
memory for this parameter. 

ERROR CODES 

CFIDR^UNUSABLE_OID: 
netlistView is not a usable OID. 

CFIDR^INVALIDjOBJECTTYPE: 
netlistView is not the OID of a NetlistView. 

CFIDR_INVALID_NAME: 

the name parameter is not a valid string or is not a legal name. 

CFIDR^OBJECT^NOTJOUND: 
no Net with the specified name exists. 

CFIDRJNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NOJERROR: 
no error occurred. 



5.13.11 cfidrNetlistViewFindPortByName 

DECLARATION 

cfidrPortldT cfidrNetlistViewFindPortByName( 
cfidrNetlistViewIdT netlistView, 
cfidrStringTname, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the Port (either PortBundle or Ports calar) with the specified name that is within 
the Ports relationship defined for the NetlistView specified by netlistView. All Ports are scoped to their 
Owner (either NetlistView or PortBundle), therefore Ports contained in PortBundles are not searched by 
this function. 

RETURN VALUE 

The return value is a cfidrPortldT referring to the Port just found. If an error occurs, a Null OID is 
returned. 

PARAMETERS 

netlistView (input) The OID of the NetlistView from which the Port is to be found, 
name (input) The name of the Port. 
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error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
memory for this parameter. 



ERROR CODES 



CFIDR_UNUSABLE_OID: 
netlistView is not a usable OID. 



CFIDRJNVALIDjOBJECTTYPE: 
netlistView is not the OID of a NetlistView. 

CFIDRJfrJVALID_NAME: 

the name parameter is not a valid string or is not a legal name. 

CFIDRjOBJECT_NOT_FOUND: 
no Port with the specified name exists. 

CFroRJNTERNAL_SYSTEMJERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 



5.13.12 cfidrNetlistViewGetlnsts 

DECLARATION 

cfidrlnstsIdT cfidrNetlistViewGetInsts( 
cfidrNetlistViewIdT.neUistView, 
cfidrErrorT *eiror) 

DESCRIPTION 

This function initiates a traversal of all the Insts at the end of the Insts relationship for the NetlistView 
specified by netlistView. 

RETURN VALUE 

The return value is a cfidrlnstsIdT referring to an Iterator ID that iterates over Insts. A valid Iterator ID 
is always returned, even when an error occurs. In the case of an error, calling the cfidrlterNextlnstO 
function returns a Null OID. 

PARAMETERS 

netlistView (input) The OID of a NetlistView for which the Insts relationship is to be traversed. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 
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ERROR CODES 

CFIDRJJNUSABLE_OID: 
netlistView is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
netlistView is not the OID of a NetlistView. 

CFIDR_INTERNAL_SYSTEMJERROR: 
some other error occurred. 

CFIDR_NQJERROR: 
no error occurred. 

POST-CONDITIONS 

The cfidrlterNextlnstO function returns the next Inst OID in the Insts relationship. 

If no objects are currently present in the Insts relationship, an error is not returned but the first call to 
cfidrlterNextlnstO returns a Null OID. 

REFERENCE 
cfidrlterNextlnstO 



5.13.13 cfidrNetlistViewGetNets 

DECLARATION 

cfidrNetsIdT cfidrNetlistViewGetNets( 
cfidrNetlistViewIdT view, 
cfidrlterModeT mode, 
cfidrErroiT *eiror) 

DESCRIPTION 

This function initiates a traversal of all of the Nets (NetBundles, NetBusses, or NetScalars) at the end of 
the Nets relationship defined for the View specified by view. 

RETURN VALUE 

The return value is a cfidrNetsIdT referring to an Iterator ID that iterates over Nets. A valid Iterator ID is 
always returned, even when an error occurs. In the case of an error, calling the cfidrlterNextNetO 
function returns a Null OID. 

PARAMETERS 

view (input) The OID of a NetlistView for which the Nets relationship is to be traversed. 
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^^TSJ 1 * 5 mode ±at deterraine s which Nets are returned. The current valid values are 
CFIDRJTER^SCALARS, CFIDRJTERJBUNDLES, CFIDRJTER_To1 and CHD^jTeRALL 
See the Pre-Conditions below for more detail on how these modes behave. tR-ALL. 

Tmen^^^^ 
ERROR CODES 

CFIDR_UNUSABLE_OID: 
view is not a usable OID. 

CFIDRJNVALIDjOBJECTTYPE: 
view is not the OID of a NetlistView. 

CFIDRJNVALIDJTERMODE: 
mode is not a valid IterMode. 

CFIDR_INTERNAL_SYSTEMJERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

PRE-CONDITIONS 

Returns all Nets owned by the NetiistView. The Nets returned depends on the mode argument specified. 
worfe=CFIDR_ITER_TOP 

Returns all those Nets (NetBundles, NetBusses, or NetScalars) which are not contained in a NetBundle. 

/no</e=CFIDR_ITER_SCALARS 

N . et f I ° a !f S n 0Wn I ? d * me NetiistView, regardless of whether they are contained in a 
wetBundle or not. No NetBundles are output with this mode, only NetScalars. This mode lets the 
apphcatton effectively see the View as a scalar netlist 

morfe=CFIDR_ITER_BUNDLES 

Returns all the NetBundles owned by the NetiistView. No NetScalars are output. 
mo<fe=CFIDR_JTER_ALL 

Returns all the Nets (NetBundles, NetBusses, or NetScalars) owned by the NetiistView. This mode 
differs from CFIDR_ITER_TOP in that NetScalars contained in a Bundle are also returned. This mode 
is a combination of the SCALARS and BUNDLES modes. 

POST-CONDITIONS 

The cfidrlterNextNetO function returns the next Net OID in the Nets relationship. The next Net 
returned must obey the return mode as specified via die mode argument 

If no objects are currently present in the Nets relationship, an error is not returned but the first call to 
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cfidrlterNextNetO returns a Null OID. 
REFERENCE 

cfidrlterNextNetO 



5.13.14 cfidrNetlistViewGetPorts 

DECLARATION 

cfidrPortsIdT cfidrNetlistViewGetPorts( 
cfidrNetlistViewIdT view, 
cfidrlterModeT mode, 
cfidrErrorT *error) 

DESCRIPTION 

This function initiates a traversal of all of the Ports (PortBundles, PortBusses, or PortScalars) at the end 
of the Ports relationship defined for the NetlistView specified by view. 

RETURN VALUE 

The return value is a cfidrPortsIdT referring to an Iterator ID that iterates over Ports. A valid Iterator ID 
is always returned, even when an error occurs. In the case of an error, calling the cfidrlterNextPortO 
function returns a Null OID. 

PARAMETERS 

view (input) The OID of a NetlistView for which the Ports relationship is to be traversed. 

mode (input) The mode mat determines which Ports are returned. The current valid values are 
CFIDRJTERJSCALARS, CFIDRJTERJBUNDLES, CFIDRJTER.TOP, and CFIDR_|TER_ALL. 
See the Pre-Conditions below for more detail on how these modes behave. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
view is not a usable OID. 

CFIDRJ[NVALID_OBJECTrYPE: 
view is not the OID of a NetlistView. 

CFIDRJNVALID JTERMODE: 
mode is not a valid IterMode. 

CFIDR w rNTERNAL_SYSTEM_ERROR: 
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some other error occurred. 

CFIDRJ*0_ERROR: 
no error occurred. 

PRE-CONDITIONS 

Returns all or some of the Ports directly or indirectly owned by the NetlistView. 

Ports in a View each have a unique position in the list of Ports owned by the NetlistView. The positions 
in this list axe numbered from 0 for the "leftmost" or first position monotonically increasing by 1 up to 
one less than the size of the list. The order in which the Ports are returned is by increasing position 
starting with 0. Note that the Position of a given Port at a given time is determined by the various 
operations that have been performed on this list including: 

(1) the position specified when a Port is created in a View, 

(2) the position specified when a Port's owner is changed to the View, and 

l^i? 6 ^ ppearance (from PortBundles) and disappearance (into PortBundles) of Ports at or to the 
left" of the position of the given Port. 

The Ports returned depends on the mode argument specified. 

/noJe=CFIDR_ITER_TOP 

Returns all those Ports (PortBundles, PortBusses, or PortScalars) which are owned directly by view (i e 
not owned by a PortBundle). 

/«orfe=CFIDR_ITER_SCALARS 

Returns all the PortScalars in view, regardless of whether they are contained in a PortBundle or not No 
PortBundles are output with this mode. 

mo*fe=CFIDRJTER_JJTJNDLES 

Returns all the PortBundles owned directly or indirectly by view. No PortScalars are output with this 
mode. 

/Morfe=CFIDR JTER_ALL 

Returns all the Ports (PortBundles, PortBusses, or PortScalars) directly or recursively in view. This 
mode differs from CFIDRJTER_TOP in that Ports contained indirectly in PortBundles are also 
returned. 

The order for all modes except CFIDR_JTER_TOP is determined by depth-first recursion. 

The Port name scoping rules state that Port names need only be unique within their owner (either the 
View or a PortBundle). Thus, in any mode except CFIDR_ITER_TOP two Ports with the same name 
may be returned that are completely different objects. The function cfidrObjectlsSameO can be used to 
determine if any two ports are the same. 

POST-CONDITIONS 

The cfidrlterNextPortO function returns the next Port OID in the Ports relationship. 

If no objects are currently present in the Ports relationship, an error is not returned but the first call to 
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cfidrlterNextPortO returns a Null ODD. 

REFERENCE 

cfidrlterNextPortO 

cfidrPortSetOwnerPortBundleO 

cfidrPortSetOwnerViewO 



5.13.15 cfidrViewGetOwner 

DECLARATION 

cfidrCellldT cfidrViewGetOwner( 
cfidrViewIdT view, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the Cell at the end of the Owner relationship for the View specified by view. The 
Owner relationship is defined when an object is created and cannot be modified. 

RETURN VALUE 

The return value is a cfidrCellldT referring the Cell at the end of the Owner relationship. If an error 
occurs, a Null OID is returned. 

PARAMETERS 

view (input) The OID of the View whose Owner relationship is to be followed. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. " 

ERROR CODES 

CFIDR_TJNUSABLE_OID: 
view is not a usable ODD. 

CFIDR_INVALID_OBJECTTYPE: 
view is not the OID of a View. 

CFIDIUNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NQ_ERROR: 
no error occurred. 

REFERENCE 
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cfidrCellGetViewsO 



5.13.16 cfidrViewGetViewType 

DECLARATION 

cfidrStringT cfidrViewGetViewType( 
cfidrViewWT view, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns the ViewType attribute of the View specified by view. 
RETURN VALUE 

krttiSed ValUC iS 3 cfidrStringT resenting the value of the ViewType attribute. On error the string 
PARAMETERS 

view (input) The OID of the View whose ViewType attribute is desired. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
tne memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
view is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
view is not the OID of a View. 

CFIDR_INTERNAL_S YSTEM_ERROR : 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

REFERENCE 

cfidrCellCreateEncapsulatedViewO 
cfidrCellCreateNetlistViewO 



5.13.17 cfidrViewPurge 
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DECLARATION 

cfidrVoidT cfidrViewPurge( 
cfidrViewIdT view, 
cfidrErrorT *error) 

DESCRIPTION 

This function purges the View specified by view. The purge operation removes any changes made to an 
object since the last save or open. See the POST-CONDITIONS for more specific information. 

PARAMETERS 

view (input) The OID of the View to purge. The View hierarchy owned by view is also purged. 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDRJJNUSABLE^OID: 
view is not a usable OID. 

CTIDR_INVALID_OBJECTTYPE: 
view is not the OID of a View. 

CFIDR_JNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NOJERROR: 
no error occurred, 

PRE-CONDITIONS 

A View can be purged regardless of the access mode of any object 
POST-CONDITIONS 

Any OIDs referring to the purged view are made unusable. They may be reused to refer to other Views 
at some point, so the application cannot assume that if the purged View is again made available (via 
open, create, etc.), that it will have the same OID. 

It is neither required nor precluded that whatever encapsulated information referenced by the 
EncapsulatedView be purged since this can be system dependent. 

The effect of purging a NetlistView is to also purge the entire object hierarchy owned by that 
NetlistView. 

Policy: The purge operation removes any changes made to the View since the last save or open. The 
View then becomes unavailable and its OID becomes unusable. Opening the View again assigns the 
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View an OID and makes it available for updating. 

An example implementation that provides this behavior would make an in-memory copy of the view 
when it was opened. Any changes to the view, or to any of its contained objects, would be made to the 
in-memory copy of the view. The effect of a "purge" is to delete the in-memory copy of the view, 
leaving the on-disk persistent view data unchanged. 

Policy: Similar to open, purge also recursively walks the ownership hierarchy of Objects rooted by the 
specified View and purges all the Objects in this hierarchy. Unlike open, purge continues walking the 
ownership hierarchy when it encounters an Object which can be purged individually. Thus purge 
behaves similarly to save in this respect. 

Rationale: Consider the information model and take into account the policy that only Libraries and 
Views can be purged. Purging a View removes the View's Objects (Nets, Ports, Insts, and Props). 
Purging a Lib not only purges the Lib and Cells, it also purges all the Views as well. 

Rationale: When opening a Lib, opening all the Views automatically is probably undesirable in most 
situations. However, when purging a Lib, it does not make sense to only purge the Lib and Cells and not 
the Views. 

Policy: Purging a NetlistView "A" (and its owned Ports) that is referenced in another NetlistView "B" 
via the Describer relationship of an Inst (and of its Portlnsts) only breaks the Describer relationships 
from the Inst (to "A") and the Portlnsts. The Inst and Portlnsts are not themselves purged nor is 
NetlistView "B". 

REFERENCE 

cfidrLibSaveO 

cfidrLibPurgeO 

cfidrViewSaveO 



5.13.18 cfidrViewSave 

DECLARATION 

cfidrVoidT cfidrViewSave( 
cfidrViewIdT view, 
cfidrErrorT *error) 

DESCRIPTION 

This function saves the View specified via view. The effect of saving a View is to also save the entire 
Object hierarchy owned by the saved View. Saving a View makes all updates to objects in the View's 
hierarchy persistent If the View has been opened for CFIDRJtEAD, changes to the Views contained in 
the View that are open for CFIDRJUPDATE will be made persistent. 

PARAMETERS 

view (input) The OID of the View to save. The Objects owned by view are also saved. 
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error (output) A pointer to the error returned if this function Ms. The caller is responsible for allocating 
die memory used by this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
view is not a usable OID. 

CFIDR_INVALID_OBECTTYPE: 
view is not die Off) of a View. 

CFIDR_INTERNAL_SYSTEMLERROR: 
some other error occurred. 

CFIDRJMO _ERROR: 
no error occurred. 

POSTCONDITIONS 

Views cannot be saved completely independentiy of Libs because of the issue of referential integrity for 
the View's Cell's catalog entry in the Lib. Thus when a View is saved, some data associated with the 
owning Lib of the View will also likely have to be saved. 

The Lib must also be saved such that the Cell with this View is saved. Depending on the implementation 
this may already be true and thus no further Lib save is needed. However, if this is a newly-created 
View since the last save of the Lib with the Cell containing this view, a partial save will be necessary to 
ensure that the Cell reference to this view is now persistent. 

Other newly created but not yet saved Views are not included in the saved Lib until they are explicidy 
saved. However those Views still appear in "memory" unless the Cell containing them is purged. 

Once a View is saved, it is known and available for opening across session boundaries until deleted via 
cfidrObjectDestroyO- 

Saving does not invalidate OIDs referring to the saved View. 
REFERENCE 

cfidrObjectDestroyO 
cfidrPIQuitQ 
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6 View Selection 



6.1 View Selection Overview 

View Selection allows selection between different, alternative but substitutable views in a design 
hierarchy. While the Describer attribute of an Inst is always a specific Cell and View (namely, the 
describerView parameter supplied to cfidrViewCreatelnstO when the Inst is created), it is possible 
when traversing a design hierarchy to choose a different, equivalent View. Certainly as long as the Ports 
of the alternative describer View have the same name, number, and directions of the Portlnsts on the 
Inst, it is reasonable to choose the alternative View. 

NOTE: While it is certainly allowed, there is no requirement specified in DR 1 .0 that the Ports of 
multiple NetlistViews of Cell must match in name, number, direction, or types. Furthermore, it is 
by definition outside of the scope of DR 1 .0 to specify what sort of "ports" are in an "outside' 1 
View that is encapsulated by a cfidrEncapsulatedView or to specify how those "ports" correspond 
to the Ports in any particular cfidrNetlistView. 

View Selection provides rules for choosing alternatives that make it possible for the user to insure that 
the design hierarchy is traversed in the same manner by two different tools. View Selection does not, at 
this time guarantee that the Views selected are equivalent to the original describer. That is up to the user 
of the system and, in particular, the creator of the selector objects. As with the other features of the CFI 
DR-PI, a mechanism is defined but methodology and policies are left to the CAD system integrator. 

It is anticipated that the typical use of this mechanism will be to selectively specify the use of 
substructure versus available behavioral descriptions when a design is being expanded for simulation. 
As such, it will work naturally with the Encapsulated View mechanism, allowing either choices of 
multiple connectivity models (in the scope of the CFI 1 .0 DR Information Model and Programming 
Interface) or alternative "foreign" models which must be manually synchronized to the (interface) Ports 
in the other connectivity views. 

This overview first describes the additional objects needed for view selection and then describes the 
types of routines needed for view selection. It is followed by a more formal description of the 
Information Model and then by the function descriptions for the DR-PL 



6.1.1 Disclaimer 

This is a very preliminary version of a more general capability for ViewSelection anticipated to be in 
CFI 2.0 Design Representation. That version of CFI DR is expected to support versioning and rebinding 
of View references and therefore a more general concept of instantiation. There will also likely be a 
CFI-defined standard mechanism for mapping between Views and the objects inside of them. 



6.1.2 View Selection Objects 

V 

http://www.si2.org/si2jublications/htalSpecs/DR/part6.fa4.htrnl 



6/23/2004 



Page 2 of 29 



The object types that are used to support view selection are: 

1 . SelectorSet— this object contains a set of prioritized ViewSelectors and a set of prioritized 
LibrarySelectors. The ViewSelectors are used to specify which Views should be selected and the 
LibrarySelectors are used to specify where to look for Views. 

LibrarySelector— this specifies which Libraries (Libs) may contain possible Cells to be selected. 
ViewSelector— this specifies which View to select. A ViewSelector may be either a 
VjewNameSelector or a ViewTypeSelector. A ViewSelector consists of source attributes and 
destination attributes. The source attributes specify that a ViewSelector should only be applied in 
selecting a View for a Cell if the Cell matches the source attributes. Currently the source attributes 
are LibName and CellName. The destination attributes specify which ViewName or ViewType to 
select* 

VjewNameSelector— this is a subtype of selector which contains selectors that specify particular 
ViewNames upon which to select. It may also specify a source LibName and/or source CellName 
which must match the Name attribute of the Cell for which we are selecting a View in order for 
the rule to be applied. 

ViewTypeSelector— mis is a subtype of a selector which contains selectors that specify particular 
ViewTypes to select upon. It may also specify a source LibName and/or source CellName which 
must match the Name attribute of the Cell for which we are selecting a View in order for the rule 
to be applied. 



6.13 View Selection Operations 

View Selection is accomplished with a set of LibrarySelectors which specify where Cells and their 
Views may be found and a set of ViewSelectors which specify which Cells and their Views should be 
selected. The selection routine cfidrSelectorSetSelectViewO looks for the View in the Libraries (Libs) 
specified by the LibrarySelectors. cfidrSelectorSetSelectViewO starts at the first ViewSelector and sees 
whether it selects a particular View. It continues through the ViewSelectors in order of creation until it 
finds a Selector which selects exactly one View. When cfidrSelectorSetSelectViewO finds a 
ViewSelector that specifies a particular View it returns that cfidrViewIdT to the calling program. 

There are four types of view selection routines, CREATION, PERSISTENCY, ATTRIBUTE ACCESS 
AND SELECTION: 

1 . CREATION: The creation routines create the SelectorSets and the various kinds of selectors in the 
Selectors ets. 

cfidrPICreateSelectorSetO; 
cfidrSelectorSetCreateLibrarySelectorO; 
cfidrSelectorSetCreateViewNameSelectorO; 
cfidrSelectorSetCreateViewTypeSelectorO; 

PERSISTENCY: 

cfidrPIOpenSelectorSetO; 

cfidrSelectorSetPurgeO; 

cfidrSelectorSetSaveO; 

ATTRIBUTE ACCESS: The attribute access routines access the created SelectorSets and 

selectors. It is currendy not possible to modify the attributes of an existing selector. 

cfidrlterNextLibrarySelectorO; 

cfidrlterNextViewSelectorO; 

cfidrLibrarySelectorGetLibNameO; 

cfidrViewNameSelectorGetCeUNameO; 
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cfidrViewNameSelectorGetLibNameO; 

cfidrViewNameSelectorGetViewNameO; 

cfidrViewTypeSelectorGetCellNameO; 

cfidrViewTypeSelectorGetLiblNameO; 

cfidrViewTypeSelectorGetViewTypeO; 

SELECTION: This routine is used to select a particular view given a SelectorSet and a cell 
cfidrSelectorSetSelectViewQ; 



6.1.4 View Selection Examples 

1 . ViewNameSelector with specified LibName and CellName 

SrcLibName : mylib 
SrcCellName : AND2 
DestViewName : beh 

This ViewNameSelector selects any View named "beh" for a Cell with the CellName "AND2" and a Lib 
with LibName "mylib" if a View with the name "beh" exists for the Cell "AND2" in any of the Libraries 
specified by the LibrarySelectors. 

ViewNameSelector with no specified LibName and CellName 
SrcLibName : 
SrcCellName: 
DestViewName : netlist 

If the user has Libraries (Libs) whose Name attributes are: "LibA", "LibB", and "LibC" (created in this 
order) specified in the LibrarySelector and "LibA" has a View whose Name attribute is "schematic," 
LibB" has a View named "netlist," and "LibC" has Views named "netlist" and "schematic" for the Cell 
this rule would return the "LibB" View named "netlist" 

ViewNameSelector with specified CellName but no specified LibName. 
SrcLibName: 
SrcCellName : Adder 
DestViewName : schematic 

This works like example 2 except that it is only applied to Cells whose Name attribute is "Adder," this 
time looking for Views whose Name attribute is "schematic." 

ViewNameSelector with specified LibName but no specified CellName. 

SrcLibName : VendorLib 
SrcCellName: 
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DestViewName : VendorSim 

TTjis works like example2 except that it is only used with Cells whose Lib Name attribute is 
VendorLib. 



6.2 View Selection Information Model 



6.2.1 EXPRESS-G 




Figure 7.1 View Selection Information Model 

6.2,2 Entity: SelectorSet 

ENTITY cf idrSelectorSet 

SUBTYPE OF (cfidrNamedObject) ; 
ViewSelectors: LIST[0:?] of 

UNIQUE cfidrViewSelector; 
LibrarySelectors : LIST[0:?] of 
UNIQUE cfidrLibrarySelector; 
END_ENTITY; 

6.2 J Entity: ViewSelector 
ENTITY cf idrViewSelector 

SUBTYPE OF (cfidrObject) 

ABSTRACT SUPERTYPE OF (ONEOF 

(cf idrViewNameSelector, cf idrViewTypeSelector) ) ; 
Owner: cf idrSelectorSet 
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ENDJ2NTITY; 

6.2.4 Entity: ViewNameSelector 

ENTITY cfidrViewNameSelector 

SUBTYPE OF (cfidrViewSelector) ; 

LibName: OPTIONAL cf idrStringT; 

CellName: OPTIONAL cf idrStringT; 

ViewName: cf idrStringT; 
END__ENTITY; 

The LibName and CellName are optional attributes which are used to limit the application of a particular 
Selector to only those cells whose LibName and/or ViewName matches the cell whose view selection is 
desired. 

6.2.5 Entity: ViewTypeSelector 

ENTITY cfidrViewTypeSelector 

SUBTYPE OF (cf idrSelector) ; 

LibName: OPTIONAL cf idrStringT ; 

CellName: OPTIONAL cf idrStringT; 

ViewType: cf idrStringT; 
END_ENTITY; 

The LibName and CellName are optional attributes which are used to limit the application of a particular 
Selector to only those cells whose LibName and/or ViewName matches the cell whose view selection is 
desired. 

6.2.6 Entity: LibrarySelector 

ENTITY cfidrLibrarySelector 

SUBTYPE OF (cfidrObject) ; 

libraryName: cf idrStringT; 

Owner: cf idrSelectorSet 
END_ENTITY; 

6.3 View Selection Data Types 

Object Identifiers 
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typedef cf idrObjectldT cf idrSelectorSetldT; 

typedef cf idrObjectldT cf idrViewSelectorldT; 

typedef cf idrObjectldT cf idrViewNameSelectorldT; 

typedef cf idrObjectldT cf idrViewTypeSelectorldT; 

typedef cf idrObjectldT cf idrLibrarySelectorldT; 

Iterator Identifiers 

typedef cfidrlterldT cf idrViewSelectorsIdT; 

typedef cfidrlterldT cf idrLibrarySelectorsIdT; 

Types of Objects 

Additions to cfidrObjectTypeT 
typedef enum { 







CFI DR_UNDEF INED_OB JECTTYPE 




1, 


CFIDR_LIB 




2, 


CFIDR_CELL 




3, 


CFIDR_PORTBUNDLE 




4, 


CFIDR_PORTBUS 




5, 


CFIDR_PORTSCALAR 




6, 


CFIDR_INST 




7, 


CFIDR_PORTINSTBUNDLE 




8, 


CFIDR_PORTINSTBUS 




9, 


CFIDR_PORTINSTSCALAR 




10, 


CFIDR_NETBUNDIiE 




11. 


CFIDR^NETBUS 




12, 


CF I DR_NETSCALAR 




13, 


CFIDR^PROP 




14, 


CFIDR_NETLISTVIEW 




15, 


CF I DR_ENC APSULATEDVI EW 




16, 


CFIDR_SELECTORSET 




17, 


CFIDRJLIBSELECTOR 




18, 


CFIDR_VI EWNAMESELECTOR 




19, 


CFIDR_VIEWTYPESELECTOR 




20 


C F I DR__MAX_OBJECTTYPE 



> cfidrObjectTypeT; 



6.4 View Selection Programming Interface 



6.4.1 cfidrlterNextLibrarySelector 

DECLARATION 

cfidrLibrarySelectorIdTcfidrIterNextLibraiySelector( 
cfidrLibrarySelectorsIdT iterator, 
cfidrErrorT *error) 

DESCRIPTION 

The function returns another LibrarySelector object from the Iterator ID specified via iterator. 
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RETURN VALUE 

If there are any more LibrarySelectors in the iterator, the return value is an OID of type 
cfidrLibrarySelectorldT for the next LibrarySelector. If an error occurs or there are no more 
LibrarySelectors, a Null OID is returned. If there are no more LibrarySelectors this is not an error. 

PARAMETERS 

iterator (input) The Iterator ID of an Iterator over LibrarySelector objects. 

error (output) The error returned if this function fails. The caller is responsible for allocating the 
memory used by this parameter. 

ERROR CODES 

CFIDR_JNVALID _ITER: 
iterator is not a valid Iterator. 

CFIDRJNVALID _JTER_TYPE: 

iterator is not an Iterator of LibrarySelectors. 

CFIDRJNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 



6.4.2 cfidrlterNextSelectorSet 

DECLARATION 

cfidrSelectorSetldT cfidrIterNextSelectorSet( 
cfidrSelectorSetsIdT iter, 
cfidrErrorT *error) 

DESCRIPTION 

This function returns another Selector Set object from the Iterator ID specified via iter. 
RETURN VALUE 

The return value is a cfidrSelectorSet referencing the Selector Set object just iterated. 

If an error occurs or there are no more Selector Sets to iterate, a Null OID is returned. If there are no 
more Selector Sets to iterate, this is not an error. 

PARAMETERS 

iter (input) The Iterator ID representing an Iterator of Selector Set objects. 
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error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
the memory used by this parameter. 

ERROR CODES 

CFIDRJNVALIDJTER: 

iter is not the ID of a valid Iterator. 

CFIDRJNVALID_JTER_TYPE: 

iter is not the ID of an Iterator of Selector Set objects. 

CFIDIUNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDRJNOJERROR: 
no error occurred. 

PRE-CONDITIONS 

The iter argument must have been returned via a previous call to cfidrPIGetSelectorSetsO- 
POST-CONDITIONS 

If the Selector Set is not already open, this function will attempt to open it. If the open fails, the error 
return for this function will be the error return of the open. The iteration sequence can continue after a 
failed Selector Set open. 

REFERENCE 
CfidrPIGetSelectorSetsO 



6.4.3 cfidrlterNextViewSelector 

DECLARATION 

cfidrViewSelectorIdTcfidrIterNextViewSelector( 
cfidrViewSelectorsIdT iterator, 
cfidrErrorT *error) 

DESCRIPTION 

The function returns another ViewSelector object from the Iterator ID specified via iterator. 
RETURN VALUE 

If there are any more ViewSelectors in the iterator, the return value is an OID of type 
cfidrViewSelectorldT for the next ViewSelector. If an error occurs or there are no more ViewSelectors, 
a Null OID is returned. If there are no more ViewSelectors this is not an error. 
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PARAMETERS 

iterator (input) The Iterator ID representing an Iterator ViewSelector objects. 

error (output) The error returned if this function fails. The caller is responsible for allocating the 
memory used by this parameter. 

ERROR CODES 

CFIDRJNVALID.JTER: 
iterator is not a valid Iterator. 

CFIDR_INVALID_JTER_TYPE: 
iterator is an Iterator of ViewSelectors. 

CFIDR_JNTERNAL_SYSTEMJERROR: 
some other error occurred. 

CFIDR_MOJERROR: 
no error occurred. 



6.4.4 cfidrLibrarySelectorGetLibraryName 

DECLARATION 

cfidrStringT cfidrLibrarySelectorGetLibraryName( 
cfidrLibrarySelectorldT libraiySelector, 
cfidrErrorT *error) 

DESCRIPTION 

Returns the IAbraryName attribute of the LibraiySelector specified in UbratySelector. 
RETURN VALUE 

The return value is of type cfidrStringT and is the value of the IAbraryName attribute of 
UbratySelector. On error a Null string (" ") is returned. 

PARAMETERS 

UbrarySelector (input) The OID of the LibraiySelector whose LibraryName attribute is desired. 

error (output) The error returned if this function fails. The caller is responsible for allocating the 
memory for this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
UbrarySelector is not a usable OID. 
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CFIDRJNVALID_OBJECTTYPE: 
UbrarySelector is not the OID of a LibrarySelector. 

CFIDRJNTERNALJSYSTEM JERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 



6.4.5 cfidrPICreateSelectorSet 

DECLARATION 

cfidrSelectorSetldT cfidrPICreateSelectorSet 

cfidrStringTname, 

cfidrErrorT *error) 

DESCRIPTION 



Creates a SelectorSet with the specified name. The SelectorSet may contain a prioritized/ordered list of 
ViewSelectors and LibrarySelectors. The Selectors are prioritized based on the order of creation The 
first Selector created will have the highest priority. The second Selector created will have the next 
highest priority. 

RETURN VALUE 

The return value is an OID of type cfidrSelectorSetldT for the SelectorSet just created. If an error 
occurs a Null OID is returned. 

PARAMETERS 

name (input) The string representing the name of the SelectorSet to be created. 

error (output) The error returned if this function fails. The caller is responsible for allocating memory 
for this parameter. 

ERROR CODES 



CFIDR_INVALID_NAME 

the name parameter is not a valid string or is not a legal name. 

CFIDR_OBJECT_ALREADYJEXISTS: 

a SelectorSet with the same name already exists. 

CFIDR_INTERNAL_SYSTEM_ERROR 
some other error occurred. 



CFIDRJNO JERROR: 
no error occurred. 
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PRE-CONDITIONS 

The name of the SelectorSet must conform to the character set for name strings. No SelectorSet with the 
same name may exist. 

The system implementing the DR-PI is responsible for knowing about all SelectorSets created and saved 
in previous sessions or created in the current session when determining whether the SelectorSet already 
exists. The SelectorSet need not be opened to be considered as existing. 

Each system implementing the DR-PI is responsible for creating and maintaining the SelectorSet's data- 
storage area. The application using the PI need not have any prior knowledge of where the data 
physically resides. 

If cfidrPIINITO has not been called previously, it is called automatically before this function. 

POST-CONDITIONS 

A SelectorSet is created with no ViewSelectors or LibrarySelectors. 

A created SelectorSet is not persistent across session boundaries until it is saved. 

6.4.6 cfidrPIGetSelectorSets 

DECLARATION 

cfidrSelectorSetsIdT cfidrPIGetSelectorSets( 
cfidrErrorT *error) 

DESCRIPTION 

This function initiates a traversal of all the Selector Sets known by the DR-PI. 
RETURN VALUE 

The return value is a cfidrSelectorSetsIdT referring to an Iterator ID that iterates over Selector Sets. 

If an error occurs in cfidrPIGetSelectorSetsO, the error output argument is set and a valid Iterator ID is 
returned. In this case, calling the cfidrlterNextSelectorSetO function returns the Null OID. 

PARAMETERS 

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating 
Ihe memory used by this parameter. 

ERROR CODES 

CFIDR_JNTERNAL_SYSTEM_ERROR: 
a system error occurred. 
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CFIDR_NOJ3RROR: 
no error occurred. 

POST-CONDITIONS 

The cfidrlterNextSelectorSetO function returns the OID of the next Selector Set known by the DR-PI. 

If no Selector Sets are known by the PI, an error is not returned but the first call to 
cfidrlterNextSelectorSetO returns the Null OID. 

If cfidrPIInitO has not been called before, this function will call it before proceeding. 
REFERENCE 

cfidrlterNextSelectorSetO 
cfidrPIInitO 

6.4.7 cfidrPIOpenSelectorSet 

DECLARATION 

cfidrSelectorSetldT cfidrPIOpenSelectorSet( 
cfidrStringT name, 
cfidrErrorT *error) 

DESCRIPTION 

This function opens a SelectorSet specified via name and allows it to be updated. 
RETURN VALUE 

The return value is an OID of type cfidrSelectorSetldT for the SelectorSet just opened. If an error 
occurs, a Null OID is returned. 

PARAMETERS 

name (input) A string representing the name of the SelectorSet to be opened. 

error (output) The error returned if this function fails. The caller is responsible for allocating memory 
used by this parameter. 

ERROR CODES 
CFIDR_INVALID_NAME: 

name parameter is not a valid string or is not a legal name. 

CFIDR_OBJECT_NOTJ?OUND: 

no SelectorSet with the specified name exists. 
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CFIDR^OPENJ?OR_UPDATE_FAILED: 

a SelectorSet with the specified name exists or is open already but it is not possible to update it. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_ J NO_ERROR: 
no error occured. 

PRE-CONDITIONS 

If the SelectorSet does not exist, it is not created automatically. 

If cfidrPIINITO has not been called previously, it is called automatically before this function. 
POST-CONDITIONS 

If the SelectorSet has been previously opened but not purged in the current session, then opening it 
again returns the same Off). In this case, the error output argument should be set to 
CFIDR_NO_ERROR to denote this fact even thought it is not an error. 



6.4.8 cfidrSelectorSetCreateLibrarySelector 

DECLARATION 

cfidrLibrarySelectorldT 
cfidrSelectorSetCreateLibrarySelector( 
cfidrSelectorSetldT owner, 
cfidrStringT libraryName, 
cfidrEnorT *error) 

DESCRIPTION 

Creates a LibrarySelector in the SelectorSet specified by owner and adds it to the end of the list in the 
UbrarySelectors attribute of owner. The LibrarySelector defines which Libs are used for view selection. 

RETURN VALUE 

The return value is an Off) of type cfidrLibrarySelectorldT for the LibrarySelector just created. If an 
error occurs a Null OID is returned. 

PARAMETERS 

owner (input) The OID of the SelectorSet owning the Selector to be added. 

libraryName (input) The string representing the LibraryName of the LibrarySelector. 

error (output) The error returned if this function fails. The caller is responsible for allocating the 
memory for this parameter. 
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ERROR CODES 

CFIDR_UNUSABLE_OID: 
owner is not a usable OID. 

CFIDRJNVALID_OBJECTTYPE: 
owner is not the OID of a SelectorSet 

CFIDRJNVALID_NAME: 

the libraiyName parameter is not a valid string or is not a legal name. 

CFIDR u _INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 



6.4.9 cfidrSelectorSetCreateViewNameSelector 

DECLARATION 

cfidrViewNameSelectorldT 

cfidrSelectorSetCreateViewNameSelector( 
cfidrSelectorSetldT owner, 
cfidrStringT libName, 
cfidrStringT cellName, 
cfidrStringT viewName, 
cfidrErrorT *error) 

DESCRIPTION 

Creates a ViewNameSelector in the owner SelectorSet. This routine adds the newly created selector to 
the end of the list of ViewSelectors associated with the SelectorSet specified by owner. 

This ViewNameSelector may then be used by cfidrSelectorSetSelectViewO to select a particular view. 
Both the libName and cellName parameters are optional. They are used to specify whether a 
ViewSelector should be used for a particular Cell. If the libName and/or the cellName attributes are not 
Null strings in the newly created ViewNameSelector then they must match the Cell passed to 
CfidrSelectorSetSelectViewO in order for this ViewNameSelector to be used. 

RETURN VALUE 

The return value is an OID of type cfidrViewNameSelectorldT for the ViewNameSelector just created. 
If an error occurs a Null OID is returned. 

PARAMETERS 

owner (input) The OID of the SelectorSet owning the Selector to be added. 
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SSe^ eteSvS^ resenting the Name of a Lib to be used as a match for the function 

error (output) The error returned if this function fails. The caller is responsible for allocating the 
memory for this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
owner is not a usable OID. 

CF1DR_INVALID_0BJECTTYPE: 
owner is not the OID of a SelectorSet. 

CFIDRJTNVALID_NAME: 

either the libName, cellName, or viewName parameter is not a valid string or is not a legal name. 

CFIDRJNTERNALJ3YSTEM_ERROR: 
some other error occurred. 

CFIDR_NOJERROR: 
no error occurred 

PRE-CONDITIONS 

If the libName is a Null string, it acts like a wildcard and matches any Lib's Name. 
If the cellName is a Null string, it acts like a wildcard and matches any Cell's Name. 
POST-CONDITIONS 

This ViewNameSelector cannot have its attributes changed later. If incorrect attributes are present, the 
application writer must destroy the Selector then create new selectors) with the new attributes(s). 

REFERENCE 

cfidrSelectorSetSelectViewO 
cfidrObjectDestroyO 

6.4.10 cfidrSelectorSetCreateViewTypeSelector 

DECLARATION 
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cfidrViewTypeSelectorldT 

cfidrSelectorSetCreateViewTypeSelector( 

cfidrSelectorSetldT owner, 

cfidrStringT HbName, 

cfidrStringT cellNarae, 

cfidrStringT viewType, 

cfidrErrorT *error) 

DESCRIPTION 

Creates a ViewTypeSelector in the owner SelectorSet. This routine adds the newly created selector to 
the end of the list of ViewSelectors associated with the SelectorSet specified by owner. 

This ViewTypeSelector may then be used by cfidrSelectorSetSelectViewO to select a particular view. 
Both the hbName and cellName parameters are optional. They are used to specify whether a 
ViewSelector should be used for a particular Cell. If the HbName and/or the cellName attributes are not 
Null strings in the newly created ViewTypeSelector then they must match the Cell passed to 
CfidrSelectorSetSelectViewO in order for this ViewTypeSelector to be used. 

RETURN VALUE 

The return value is in OID of type cfidrViewTypeSelectorldT for the ViewTypeSelector just created. If 
an error occurs a Null OID is returned. 

PARAMETERS 

owner (input) The OID of the SelectorSet owning the Selector to be added. 

HbName (input) A cfidrStringT representing the Name of a Lib to be used as a match for the function 
CfidrSelectorSetSelectViewO. 

cellName (input) A cfidrStringT representing the Name of a Cell to be used as a match for the function 
CfidrSelectorSetSelectViewO. 

viewType (input) A cfidrStringT representing the ViewType of a View to be used as a match for the 
function cfidrSelectorSetSelectViewO. 

error (output) The error returned if this function fails. The caller is responsible for allocating the 
memory for this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
owner is not a usable OID. 

CFIDRJTNVALID_OBJECTTYPE: 
owner is not the OID of a SelectorSet 

CFIDR_INVALID_N AME : 

either the HbName or cellName parameter is not a legal name, or the viewType parameter is not a valid 
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string. 

CFIDRJNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR v _NO_ERROR: 
no error occurred 

PRE-CONDITIONS 

If the HbName is a Null string, it acts like a wildcard and matches any Lib's Name. 
If the cellName is a Null string, it acts like a wildcard and matches any Cell's Name. 
POST-CONDITIONS 

This ViewTypeSelector cannot have its attributes changed later. If incorrect attributes are present, the 
application writer must destroy the entire Selector then create new selector(s) with the new attributes(s). 

REFERENCE 

cfidrSelectorSetSelectViewO 
cfidrObjectDestroyO 

6.4.11 cfidrSelectorSetGetLibrarySelectors 

DECLARATION 

cfidrLibraiySelectorsIdT 
cfidrSelectorSetGetLibrarySelectors( 
cfidrSelectorSetldT selectorSet, 
cfidrErroiT *error) 

DESCRIPTION 

This function initiates traversal of all the LibrarySelectors in the LibrarySelectors list in the SelectorSet 
specified by selectorSet. 

RETURN VALUE 

The return value is a cfidrLibraiySelectorsIdT referring to an Iterator ID that iterates over 
LibrarySelectors. If an error occurs, a Null OID is returned, but the first call to 
cfidrlterNextLibrarySelectorO returns a Null OID. 

PARAMETERS 

selectorSet (input) The OID of the selectorSet for which the Selectors relation is to be traversed. 
error (output) The error returned if this function fails. The caller is responsible for allocating the 
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memory for this parameter. 
ERROR CODES 

. CFIDR_UNUSABLE_OID: 
selectorSet is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
selectorSet is not the OID of a SelectorSet. 

CFIDRJNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR w >lO_ERROR: 
no error occurred. 

POST-CONDITIONS 

The cfidrlterNextLibrarySelectorO function returns the OID of the next LibrarySelector known by the 
LibrarySelector relationship. 

REFERENCE 

cfidrlterNextLibrarySelectorO 



6.4.12 cfidrSelectorSetGetViewSelectors 

DECLARATION 

cfidrViewSelectorsIdTcfidrSelectorSetGetViewSelectore( 
cfidrSelectorSetldT selectorSet, 
cfidrErrorT *error) 

DESCRIPTION 

This function initiates traversal of all the ViewSelectors at the end of the ViewSelectors relationship 
defined for the SelectorSet specified by selectorSet. 

RETURN VALUE 

The return value is a cfidrViewSelectorsIdT referring to an Iterator ID that iterates over ViewSelectors. 
If an error occurs, a valid Iterator is returned, but the first call to cfidrlterNextViewSelectorO returns a 
Null OID. 

PARAMETERS 

selectorSet (input) The OID of the selectorSet for which the Selectors relation is to be traversed. 
error (output) The error returned if this function fails. The caller is responsible for allocating the 
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memory for this parameter. 
ERROR CODES 

CFroR._UNUSABLE_.OID: 
selectorSet is not a usable OID. 

CFIDRJNVALro^OBJECTTYPE: 
selectorSet is not the OID of a SelectorSet. 

CFIDRJNTERNALJSYSTEM JERROR: 
some other error occurred. 

CFIDR_NO_ERR0R: 
no error occurred. 

REFERENCE 

cfidrlterNextViewSelectorQ 



6.413 cfidrSelectorSetPurge 

DECLARATION 

cfidrVoidT cfidrSelectorSetPurge{ 
cfidrSelectorSetldT selectorSet, 
cfidrErrorT *error); 

DESCRIPTION 

This function purges the SelectorSet specified by selectorSet The effect of purging a SelectorSet is also 
to purge the entire Object hierarchy (all the selectors it contains) owned by the purged SelectorSet. 

PARAMETERS 

selectorSet (input) The OID of the SelectorSet to purge. All ViewSelectors and LibrarySelectors in the 
SelectorSet are also purged. 

error (output) The error returned if this function foils. The caller is responsible for allocating memory 
for this parameter. 

ERROR CODES 

CFIDRJJNUSABLE_OID: 
selectorSet is not a usable OID. 

CFIDRJNVALIDjOBJECTTYPE: 
selectorSet is not the OID of a SelectorSet. 



http://www.si2.org/si2 j)ublications/htmlSpecs/DR/part6.fin4.html 



6/23/2004 



Page 20 of 29 



CFIDR_JNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NOJERROR: 
no error occurred. 

PRE-CONDITIONS 

A SelectorSet can be purged regardless of the access mode of any object. 

POST-CONDITIONS 

Any OIDs referring to purged SelectorSets are made unusable. They may be reused to refer to other 
SelectorSets at some point, so the application cannot assume that if the purged SelectorSet is again made 
available (via, open, create, etc.) that it will have the same OID. 

Policy: The purge operation removes any changes made to an object since the last save or open. The 
object then becomes unavailable and its OID becomes unusable. Opening the SelectorSet again assigns 
the SelectorSet an OID and makes it available for updating. 

An example implementation that provides this behavior would make an in-memory copy of the 
SelectorSet when it was opened. Any changes to the SelectorSet, or to any of its contained objects, 
would be made to the in-memory copy of the SelectorSet. The effect of a "purge'' is to delete the in- 
memory copy of the SelectorSet, leaving the on-disk persistent SelectorSet data unchanged. 

Policy: Similar to open, purge also recursively walks the ownership hierarchy rooted by the specified 
SelectorSet and purges all Objects (LibrarySelectors and ViewSelectors) in this hierarchy. Unlike open, 
purge continues walking the ownership hierarchy when it encounters an Object which can be purged 
individually. Thus purge behaves similarly to save in this respect. 

REFERENCE 
cfidrSelectorSetSaveO 



6.4.14 cfidrSelectorSetSave 

DECLARATION 

cfidrVoidT cfidrSelectorSetSave( 
cfidrSelectorSetldT SelectorSet, 
cfidrErrorT *error) 

DESCRIPTION 

This function saves the SelectorSet specified via SelectorSet. The effect of saving a SelectorSet is also to 
save the entire Object hierarchy (all selectors it contains) owned by the saved SelectorSet. Saving a 
SelectorSet makes all updates to objects (selectors) in the SelectorSet's hierarchy persistent. 

PARAMETERS 
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selectors* (input) The OID of the SelectorSet to save. The ViewSelectors and LibrarySelectors of the 
selectorSet are also saved. 

error (output) The error returned if this function fails. The caller is responsible for allocating the 
memory for this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
selectorSet is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
selectorSet is not the OID of a SelectorSet. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 



6.4.15 cfidrSelectorSetSelectView 

DECLARATION 

cfidrViewWT cfidrSelectorSetSelectView( 
cfidrSelectorSetldT selectorSet, 
cfidrCellldTcell, 
cfidrErrorT *error) 

DESCRIPTION 

Uses the information in a Cell and a SelectorSet to compute the selected view. This routine uses the 
LibrarySelectors in the SelectorSet to determine which libraries contain views for selection and 
ViewSelectors to determine which selector should be selected. 

This routine looks for the view in the libraries specified by the LibraiySelectors. 
cfidrSelectorSetSelectViewO starts at the first ViewSelector and determines whether it selects a 
particular view. It continues through the ViewSelectors in order of creation until it finds a Selector 
which selects exactly one view. When cfidrSelectorSetSelectViewO finds a ViewSelector that specifies 
a particular view, it returns that view to the calling program. If multiple views are selected by a 
ViewSelector the error CFIDR_MULTIPLE_VIEWS_MATCH is set and a Null OID is returned. 

The ViewSelector specifies the selection of a particular ViewName or ViewType in the libraries 
specified by the LibrarySelector. 

The following pseudo-code illustrates a possible algorithm for this routine. It is intended to demonstrate 
functionality rather than require this particular algorithm. 

viewSelectorlterator = 
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cfidrSelectorSetGetViewSelectors(selectorSet, terror) ; 
viewSelector = 

cf idrlterNextViewSelector (viewSelectorlterator , terror) ; 
error = CFIDR_NO_VIEW_MATCHES ; 

// *** iterate through the ViewSelectors to choose a View 
while (cfidrObjectlsUsable(viewselector) == CFIDR^JTRUE) 
{ 

// *** if we should look at this selector 
if ( (viewSelector 1 s LibName is null or 

matches cells LibName) AND 

(viewSelector 1 s CellName is null or 

matches cells CellName) ) 

{ 

// look at libraries in SelectorSet 
librarylterator = 

cfidrSelectorSetGetLibrarySelectors( 

selector Set, terror); 
librarySelector = cf idrlterNextLibrarySelector ( 

librarylterator, terror) ; 
while (cfidrObjectIsUsable(libraryselector, 

terror ) = =CFIDR_TRUE ) 

{ 

if (exactly 1 view exists in 

Lib/CellName with specified name/type) 

{ 

error = CFIDR_NO_ERROR 
return view 

} 

if (>1 view found) 
{ 

error = CFIDR_jiultiple_views_match; 
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return (cfidrPIGetNullId ( ) ) ; 

} 

) 

} 

} 

// *** no object found 

return (cfidrPIGetNullId ( ) ) ; 
RETURN VALUE 



The return value is an OID of type cfidrViewIdT for the View selected. If an error occurs, a Null OID is 
returned. 

PARAMETERS 

selectorSet (input) The OID of the SelectorSet used to do view selection. 

error (output) The error returned if this function fails. The caller is responsible for allocating the 
memory for this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
selectorSet is not a usable OID. 

CFIDRJNVALIDjOBJECTTYPE: 
selectorSet is not the ODD of a SelectorSet. 

CFIDR_NO_VIEW_MATCHES : 

No matches were found for views meeting the view selection criteria specified by the selectorSet. 
CFIDR_MULTIPLE_VIEWS_MATCH: 

If a ViewTypeSelector finds multiple views of the same type in the same cell owned by library then this 
error will be returned. 

CFIDR_UNUSABLE_CELL_OID: 
cell is not a usable OID. 

CFIDR_INTERNAL_SYSTEMJERROR: 
some other error occurred. 

CFIDR_JNOJERROR: 
no error occurred. 
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6.4.16 cfidrViewNameSelectorGetCellName 

DECLARATION 

cfidrStringT cfidrViewNameSelectorGetCellName( 
cfidrViewNameSelectorldT selector, 
cfidrErrorT *error) 

DESCRIPTION 

Gets the CellName attribute of a ViewNameSelector 
RETURN VALUE 

The CellName of the ViewNameSelector. This may legally be a Null string if 
cfidrSelectorSetCreateViewNameSelectorO was called with a Null CellName string. A Null string i: 
also returned if there is an error, therefore the value at error must be checked whenever a Null string i 
returned to determine if the Null string is the correct return or if an error has occurred. 

PARAMETERS 

selector (input) The OID of the ViewNameSelector whose CellName attribute is desired. 

error (output) The error returned if this function fails. The caller is responsible for allocating the 
memory for this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
selector is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 

selector is not the OID of a ViewNameSelector. 

CFIDR_JNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred 

REFERENCE 

cfidrSelectorSetCreateViewNameSelectorO 



6.4.17 cfidrViewNameSelectorGetLibName 

DECLARATION 
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cfidrStringT cfidrViewNameSelectorGetLibName( 
cfidrViewNameSelectorldT selector, 
cfidrErrorT *error) 

DESCRIPTION 

Gets the LibName attribute of a ViewNameSelector 
RETURN VALUE 

The LibName of the ViewNameSelector. This may legally be a Null string, if 
cfidrSelectorSetCreateViewNameSelectorO was called with a Null LibName string. A Null string is 
also returned if there is an error, therefore the value at error must be checked whenever a Null string is 
returned to determine if the Null string is the correct return or if an error has occurred. 

PARAMETERS 

selector (input) The OID of the ViewNameSelector whose LibName attribute is desired. 

error (output) The error returned if this function fails. The caller is responsible for allocating the 
memory for this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
selector is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 
selector is not the OID of a SelectorSet 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

REFERENCE 

cfidrSelectorSetCreateViewNameSelectorO 



6.4.18 cfidrViewNameSelectorGetViewName 

DECLARATION 

cfidrStringT cfidrViewNameSelectorGetViewName( 
cfidrViewNameSelectorldT selector, 
cfidrErrorT *error) 

DESCRIPTION 
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Gets the ViewName attribute of a ViewNameSelector 
RETURN VALUE 

The ViewName of the ViewNameSelector. This may legally be a Null string if 
cfidi^electorSetCreateViewNameSelectorO was called with a Null ViewName string. It will be a Null 
string if there is an error. If there is an error a Null string is also returned, therefore the value at error 
must be checked whenever a Null string is returned to determine if the Null string is the correct return or 
it an error has occurred. 

PARAMETERS 

selector (input) The OID of the ViewNameSelector whose ViewName attribute is desired. 

error (output) The error returned if this function fails. The caller is responsible for allocating the 
memory for this parameter. 

RETURN VALUE 

CFIDR_UNUSABLE_OID: 
selector is not a usable OID. 

CFIDRJNVALID_OBJECTTYPE: 

selector is not the OID of a ViewNameSelector. 

CFIDR_INTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

REFERENCE 

cfidrSelectorSetCreateViewNameSelectorO 

6.4.19 cfidrViewTypeSelectorGetCellName 

DECLARATION 

cfidrStringT cfidrViewTypeSelectorGetCellName( 
cfidrViewTypeSelectorldT selector, 
cfidrErroiT *error) 

DESCRIPTION 

Gets the CellName attribute of a ViewTypeSelector. 
RETURN VALUE 
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The CellName of the ViewTypeSelector. This may legally be a Null string if 

cfidrSelectorSetCreateViewTypeSelectorO was called with a Null CellName string. If there is an error 
a Null string is also returned, therefore the value at error must be checked whenever a Null string is 
returned to determine if the Null string is the correct return or if an error has occurred. 

PARAMETERS 

selector (input) The OID of the ViewTypeSelector whose CellName attribute is desired. 

error (output) The error returned if this function fails. The caller is responsible for allocating the 
memory for this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
selector is not a usable OID. 

CFIDR_INVALID_OBJECTTYPE: 

selector is not the OID of a ViewTypeSelector. 

CFIDRJNTERNAL_SYSTEM_ERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

REFERENCE 

cfidrSelectorSetCreateViewTypeSelectorO 

6.4.20 cfidrViewTypeSelectorGetLibName 

DECLARATION 

cfidrStringT cfidrViewTypeSelectorGetLibName( 
cfidrViewTypeSelectorldT selector, 
cfidrErrorT *error) 

DESCRIPTION 

Gets the LibName attribute of a ViewTypeSelector. 

RETURN VALUE 
The LibName of the ViewTypeSelector. This may legally be a Null string if 

cfidrSelectorSetCreateViewTvpeSelectorO was called with a Null LibName string. If there is an error 
a Null string is also returned, therefore the value at error must be checked whenever a Null string is 
returned to determine if the Null string is the correct return or if an error has occurred. 
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PARAMETERS 

selector (input) The OID of the ViewTypeSelector whose LibName attribute is desired. 

error (output) The error returned if this function fails. The caller is responsible for allocating the 
memory for this parameter. 

ERROR CODES 

CFIDR_UNUSABLE_OID: 
selector is not a usable OID. 

CF1DR_INVALID_0BJECTTYPE: 

selector is not the OID of a ViewTypeSelector. 

CFIDR_INTERN AL_S YSTEM_ERROR : 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

REFERENCE 

cfidrSelectorSetCreateViewTypeSelectorO 

6.4.21 cfidrViewTypeSelectorGetViewType 

DECLARATION 

cfidrStringT cfidrViewTypeSelectorGetViewType( 
cfidrViewTypeSelectorSetldT selector, 
cfidrErrorT *error) 

DESCRIPTION 

Gets the ViewType attribute of a ViewTypeSelector. 
RETURN VALUE 

The ViewType of the ViewTypeSelector. It will be a Null string if there is an error. 
PARAMETERS 

selector (input) The OID of the ViewTypeSelector whose ViewType attribute is desired. 

error (output) The error returned if this function fails. The caller is responsible for allocating the 
memory for mis parameter. 

ERROR CODES 
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CFIDRJUNUSABLE.OID: 
selector is not a usable OID. 

CFIDR_JNVALIDjOBJECTTYPE: 
selector is not the OID of a ViewTypeSelector. 

CFIDFLJNTERNAL.SYSTEKLERROR: 
some other error occurred. 

CFIDR_NO_ERROR: 
no error occurred. 

REFERENCE 

cfidrSelectorSetCreateViewTypeSelectorO 
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